diff --git a/docs/app/app.vue b/docs/app/app.vue
index 6b651a1b35..f6762c931a 100644
--- a/docs/app/app.vue
+++ b/docs/app/app.vue
@@ -1,8 +1,20 @@
 <script setup lang="ts">
 const route = useRoute()
+
 const appConfig = useAppConfig()
 const { style, link, color } = useTheme()
 
+const colorMode = useColorMode()
+
+// Bare `d`, site-wide since the color mode button sits in the header on every
+// page. defineShortcuts disables single-key bindings while an input or a
+// contenteditable is focused, so it never eats a typed 'd'. Reads `.value`,
+// not `.preference`, so toggling out of `system` flips away from what's
+// currently on screen rather than to it.
+defineShortcuts({
+  d: () => (colorMode.preference = colorMode.value === 'dark' ? 'light' : 'dark')
+})
+
 const { data: navigation } = await useFetch('/api/navigation.json')
 
 useHead({
@@ -32,6 +44,8 @@ useFaviconFromTheme()
 const { rootNavigation, navigationByFramework } = useNavigation(navigation)
 
 provide('navigation', rootNavigation)
+
+const showLayout = computed(() => !route.path.startsWith('/examples') && route.path !== '/theme')
 </script>
 
 <template>
@@ -40,7 +54,7 @@ provide('navigation', rootNavigation)
 
     <div class="flex">
       <div class="flex-1 min-w-0" :class="[route.path.startsWith('/docs/') && 'root']">
-        <template v-if="!route.path.startsWith('/examples')">
+        <template v-if="showLayout">
           <!-- <Banner /> -->
 
           <Header />
@@ -50,7 +64,7 @@ provide('navigation', rootNavigation)
           <NuxtPage />
         </NuxtLayout>
 
-        <template v-if="!route.path.startsWith('/examples')">
+        <template v-if="showLayout">
           <Footer />
         </template>
       </div>
diff --git a/docs/app/assets/css/main.css b/docs/app/assets/css/main.css
index f811d1aee7..0c282889a3 100644
--- a/docs/app/assets/css/main.css
+++ b/docs/app/assets/css/main.css
@@ -12,6 +12,10 @@
   --container-8xl: 90rem;
 
   --font-sans: 'Public Sans', sans-serif;
+  /* Tailwind's preflight wires --font-sans and --font-mono itself, nothing
+     consumes --font-serif. Defaulting it to the body stack keeps the heading
+     rule below inert until the studio sets a serif of its own. */
+  --font-serif: var(--font-sans);
 
   --color-green-50: #EFFDF5;
   --color-green-100: #D9FBE8;
@@ -30,6 +34,28 @@
   --ui-container: var(--container-8xl);
 }
 
+/* The live counterpart of the export's heading rule, until v5 ships
+   --ui-font-heading. In `base` so `font-mono` on an h1 still wins. */
+@layer base {
+  h1, h2, h3, h4, h5, h6 {
+    font-family: var(--font-serif);
+  }
+}
+
+/* The theme studio floats its preview on a canvas recessed BEHIND the card,
+   so the two modes run opposite ways: a step down from white in light, past
+   --ui-bg in dark. Unlayered, to outrank the bg-default utility the Nuxt root
+   carries, and pointed at the neutral ramp so a themed palette reaches it. */
+body.theme-studio,
+body.theme-studio #__nuxt {
+  background-color: var(--ui-color-neutral-100);
+}
+
+.dark body.theme-studio,
+.dark body.theme-studio #__nuxt {
+  background-color: var(--ui-color-neutral-950);
+}
+
 html[data-framework="nuxt"] .vue-only,
 html[data-framework="vue"] .nuxt-only {
   display: none;
diff --git a/docs/app/components/VersionMenu.vue b/docs/app/components/VersionMenu.vue
index 916093e42a..1ebeac9c5e 100644
--- a/docs/app/components/VersionMenu.vue
+++ b/docs/app/components/VersionMenu.vue
@@ -38,7 +38,7 @@ const items = computed(() => {
       variant="subtle"
       :trailing-icon="appConfig.ui.icons.chevronDown"
       size="xs"
-      class="-mb-[6px] font-semibold rounded-full truncate"
+      class="-mb-[6px] font-semibold rounded-xl truncate"
       :class="[open && 'bg-primary/15']"
       :ui="{
         trailingIcon: ['transition-transform duration-200', open ? 'rotate-180' : undefined].filter(Boolean).join(' ')
diff --git a/docs/app/components/chat/Chat.vue b/docs/app/components/chat/Chat.vue
index 792a0c5280..a86da8df19 100644
--- a/docs/app/components/chat/Chat.vue
+++ b/docs/app/components/chat/Chat.vue
@@ -14,6 +14,9 @@ const { open, messages } = useChat()
 const { open: searchOpen } = useContentSearch()
 const { framework } = useFrameworks()
 const { resetTheme, applyThemeSettings, hasCSSChanges, hasConfigChanges } = useTheme()
+// A preset is a whole ThemeDoc, so it rides applyDoc (reset, style axis, class
+// bundle) rather than the settings channel applyTheme uses.
+const { presets, applyPreset } = useThemeStudio()
 
 const hasThemeChanges = computed(() => hasCSSChanges.value || hasConfigChanges.value)
 
@@ -32,6 +35,13 @@ function processThemeToolCalls() {
       if (name === 'applyTheme' && part.input) {
         _themeApplied.add(part.toolCallId)
         applyThemeSettings(part.input as DocsChatTools['applyTheme']['input'])
+      } else if (name === 'applyPreset' && part.input) {
+        _themeApplied.add(part.toolCallId)
+        const { preset: id } = part.input as DocsChatTools['applyPreset']['input']
+        // The model picks from an enum, but a renamed preset in a stale
+        // conversation would still resolve to nothing.
+        const preset = presets.find(entry => entry.id === id)
+        if (preset) applyPreset(preset)
       } else if (name === 'resetTheme') {
         _themeApplied.add(part.toolCallId)
         resetTheme()
@@ -129,6 +139,9 @@ function getToolMessage(state: ToolState, toolName: string, input: Record<string
     'getComponentTheme': `${readVerb} ${upperName(input.componentName || '')} theme`,
     'getThemeGuide': `${readVerb} theme guide`,
     'applyTheme': `${applyVerb} theme changes`,
+    // the preset's own name, upperName is for camelCase component ids and
+    // would render 'nuxt-ui' as 'NuxtUi'
+    'applyPreset': `${applyVerb} ${presets.find(preset => preset.id === input.preset)?.name ?? input.preset} preset`,
     'resetTheme': `${state === 'output-available' ? 'Reset' : 'Resetting'} theme to defaults`
   }[toolName] || `${searchVerb} ${toolName}`
 }
@@ -154,6 +167,7 @@ function getToolIcon(part: ToolPart): string {
     'getComponentTheme': 'i-lucide-file-text',
     'getThemeGuide': 'i-lucide-palette',
     'applyTheme': 'i-lucide-palette',
+    'applyPreset': 'i-lucide-palette',
     'resetTheme': 'i-lucide-palette'
   }
 
@@ -242,7 +256,7 @@ defineShortcuts({
           icon="i-lucide-rotate-ccw"
           color="neutral"
           variant="ghost"
-          @click="resetTheme"
+          @click="resetTheme()"
         />
       </UTooltip>
 
diff --git a/docs/app/components/content/IconsTheme.vue b/docs/app/components/content/IconsTheme.vue
index 66d45e4895..3409c83e41 100644
--- a/docs/app/components/content/IconsTheme.vue
+++ b/docs/app/components/content/IconsTheme.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import json5 from 'json5'
-import { themeIcons } from '../../utils/theme'
+import { themeIcons } from '../../utils/theme/icons'
 
 const { icon: iconSet } = useTheme()
 
diff --git a/docs/app/components/header/Header.vue b/docs/app/components/header/Header.vue
index 137a707520..d8ae3a7892 100644
--- a/docs/app/components/header/Header.vue
+++ b/docs/app/components/header/Header.vue
@@ -3,6 +3,9 @@ const route = useRoute()
 const { desktopLinks } = useHeader()
 const { open } = useChat()
 const { track } = useAnalytics()
+// The Ask-AI button skins to the applied icon pack, like the rest of the
+// studio chrome (the theme applies site-wide, so this stays consistent).
+const studioIcons = useStudioIcons()
 
 function toggleChat() {
   if (!open.value) {
@@ -39,13 +42,17 @@ function toggleChat() {
         <UButton
           color="neutral"
           variant="ghost"
-          icon="i-lucide-bot-message-square"
+          :icon="studioIcons.assistant"
           aria-label="Ask AI for help"
           @click="toggleChat"
         />
       </UTooltip>
 
-      <ThemePicker />
+      <ThemeStudioPicker />
+
+      <UTooltip text="Color mode">
+        <UColorModeButton variant="ghost" />
+      </UTooltip>
 
       <UTooltip text="Open on GitHub" class="hidden lg:flex">
         <UButton
diff --git a/docs/app/components/playground/Playground.vue b/docs/app/components/playground/Playground.vue
new file mode 100644
index 0000000000..1c43f42d70
--- /dev/null
+++ b/docs/app/components/playground/Playground.vue
@@ -0,0 +1,96 @@
+<script setup lang="ts">
+import {
+  PlaygroundInput,
+  PlaygroundCommandPalette,
+  PlaygroundCalendar,
+  // PlaygroundButtons,
+  PlaygroundNotifications,
+  PlaygroundTransactions,
+  PlaygroundTransferFunds,
+  PlaygroundInviteTeam,
+  PlaygroundAnalytics,
+  PlaygroundPinInput,
+  // PlaygroundBadges,
+  PlaygroundDashboard,
+  PlaygroundReportBug,
+  PlaygroundGoal,
+  PlaygroundSavingsTargets,
+  // PlaygroundTypography,
+  PlaygroundShortcuts,
+  PlaygroundNavigation,
+  // PlaygroundColorPicker,
+  PlaygroundEmpty,
+  PlaygroundAnnouncement,
+  PlaygroundTabs,
+  PlaygroundContributors,
+  PlaygroundAuthForm,
+  PlaygroundPrompt
+} from '#components'
+
+// Live, interactive component showcase, the Theme Studio's grid view, laid
+// out as a virtualized masonry (UScrollArea lanes) of content-sized cards à
+// la shadcn/HeroUI. Each tile is a self-contained, product-like block
+// (header + body + footer action). Overlays are only shown embedded in
+// richer examples (command palette, dashboard dropdown, select menus, auth
+// form, chat), never as bare triggers.
+const tiles = [
+  { name: 'input', component: PlaygroundInput },
+  { name: 'command-palette', component: PlaygroundCommandPalette },
+  { name: 'calendar', component: PlaygroundCalendar },
+  // { name: 'buttons', component: PlaygroundButtons },
+  { name: 'notifications', component: PlaygroundNotifications },
+  { name: 'transactions', component: PlaygroundTransactions },
+  { name: 'transfer-funds', component: PlaygroundTransferFunds },
+  { name: 'invite-team', component: PlaygroundInviteTeam },
+  { name: 'analytics', component: PlaygroundAnalytics },
+  { name: 'pin-input', component: PlaygroundPinInput },
+  // { name: 'badges', component: PlaygroundBadges },
+  { name: 'dashboard', component: PlaygroundDashboard },
+  { name: 'report-bug', component: PlaygroundReportBug },
+  { name: 'goal', component: PlaygroundGoal },
+  { name: 'savings-targets', component: PlaygroundSavingsTargets },
+  // { name: 'typography', component: PlaygroundTypography },
+  { name: 'shortcuts', component: PlaygroundShortcuts },
+  { name: 'navigation', component: PlaygroundNavigation },
+  // { name: 'color-picker', component: PlaygroundColorPicker },
+  { name: 'empty', component: PlaygroundEmpty },
+  { name: 'announcement', component: PlaygroundAnnouncement },
+  { name: 'tabs', component: PlaygroundTabs },
+  { name: 'contributors', component: PlaygroundContributors },
+  { name: 'auth-form', component: PlaygroundAuthForm },
+  { name: 'prompt', component: PlaygroundPrompt }
+]
+
+// Lanes follow the CONTAINER, not the viewport, the preview pane changes
+// width with fullscreen. Tile count follows lanes (the old per-breakpoint
+// reveal) so narrow layouts aren't one endless column.
+const scrollArea = useTemplateRef('scrollArea')
+const { width } = useElementSize(computed(() => scrollArea.value?.$el))
+const lanes = computed(() => width.value >= 1200 ? 4 : width.value >= 900 ? 3 : width.value >= 600 ? 2 : 1)
+
+const REVEAL_COUNTS = [6, 12, 19, tiles.length] as const
+const visibleTiles = computed(() => tiles.slice(0, REVEAL_COUNTS[lanes.value - 1]))
+</script>
+
+<template>
+  <UScrollArea
+    ref="scrollArea"
+    :items="visibleTiles"
+    :virtualize="{
+      lanes,
+      gap: 16,
+      estimateSize: 360,
+      paddingStart: 24,
+      paddingEnd: 24,
+      overscan: 0,
+      getItemKey: (index: number) => visibleTiles[index]!.name
+    }"
+    class="playground-grid h-full px-4 sm:px-6"
+  >
+    <template #default="{ item }">
+      <PlaygroundCard>
+        <component :is="item.component" />
+      </PlaygroundCard>
+    </template>
+  </UScrollArea>
+</template>
diff --git a/docs/app/components/playground/PlaygroundAnalytics.vue b/docs/app/components/playground/PlaygroundAnalytics.vue
new file mode 100644
index 0000000000..63e9ce431e
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundAnalytics.vue
@@ -0,0 +1,39 @@
+<script setup lang="ts">
+const extra = useStudioExtraIcons()
+const bars = [40, 65, 52, 80, 60, 95, 72]
+const days = ['M', 'T', 'W', 'T', 'F', 'S', 'S']
+</script>
+
+<template>
+  <div class="p-4 space-y-4">
+    <div class="flex items-start justify-between">
+      <div>
+        <p class="text-sm text-muted">
+          Visitors
+        </p>
+        <p class="text-2xl font-semibold text-highlighted">
+          418.2K
+        </p>
+      </div>
+      <UBadge color="success" variant="subtle" size="sm" :icon="extra.trendingUp">
+        +10%
+      </UBadge>
+    </div>
+
+    <div>
+      <div class="flex items-end gap-1.5 h-24">
+        <div
+          v-for="(bar, index) in bars"
+          :key="index"
+          class="flex-1 rounded-t-sm bg-primary/80 transition-colors hover:bg-primary"
+          :style="{ height: `${bar}%` }"
+        />
+      </div>
+      <div class="flex gap-1.5 mt-1.5">
+        <span v-for="(day, index) in days" :key="index" class="flex-1 text-center text-xs text-muted">
+          {{ day }}
+        </span>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundAnnouncement.vue b/docs/app/components/playground/PlaygroundAnnouncement.vue
new file mode 100644
index 0000000000..9b1262bb3f
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundAnnouncement.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+const appConfig = useAppConfig()
+const toast = useToast()
+</script>
+
+<template>
+  <div>
+    <div class="p-4 flex items-start gap-3">
+      <div class="flex items-center justify-center size-9 rounded-lg bg-elevated text-primary shrink-0">
+        <UIcon name="i-lucide-radar" class="size-5" />
+      </div>
+      <div>
+        <p class="font-semibold text-highlighted">
+          Observability Plus
+        </p>
+        <p class="text-sm text-muted">
+          A faster, natural-language way to explore your data. Monitoring moves to the Pro plan in 2026.
+        </p>
+      </div>
+    </div>
+
+    <div class="flex items-center justify-end gap-2 border-t border-default p-3">
+      <UButton label="Dismiss" color="neutral" variant="ghost" />
+      <UButton
+        label="Learn more"
+        color="neutral"
+        variant="subtle"
+        :trailing-icon="appConfig.ui.icons.arrowRight"
+        @click="toast.add({ title: 'Observability Plus' })"
+      />
+    </div>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundAuthForm.vue b/docs/app/components/playground/PlaygroundAuthForm.vue
new file mode 100644
index 0000000000..ebcd15e764
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundAuthForm.vue
@@ -0,0 +1,59 @@
+<script setup lang="ts">
+import * as z from 'zod'
+import type { FormSubmitEvent, AuthFormField } from '@nuxt/ui'
+
+const toast = useToast()
+const extra = useStudioExtraIcons()
+
+const fields: AuthFormField[] = [{
+  name: 'email',
+  type: 'email',
+  label: 'Email',
+  placeholder: 'Enter your email',
+  required: true
+}, {
+  name: 'password',
+  label: 'Password',
+  type: 'password',
+  placeholder: 'Enter your password',
+  required: true
+}]
+
+const providers = [{
+  label: 'Google',
+  icon: 'i-simple-icons-google',
+  onClick: () => {
+    toast.add({ title: 'Google', description: 'Login with Google' })
+  }
+}, {
+  label: 'GitHub',
+  icon: extra.github,
+  onClick: () => {
+    toast.add({ title: 'GitHub', description: 'Login with GitHub' })
+  }
+}]
+
+const schema = z.object({
+  email: z.email('Invalid email'),
+  password: z.string('Password is required').min(8, 'Must be at least 8 characters')
+})
+
+type Schema = z.output<typeof schema>
+
+function onSubmit(payload: FormSubmitEvent<Schema>) {
+  toast.add({ title: 'Submitted', description: payload.data.email })
+}
+</script>
+
+<template>
+  <div class="p-6">
+    <UAuthForm
+      :schema="schema"
+      title="Login"
+      description="Enter your credentials to access your account."
+      :fields="fields"
+      :providers="providers"
+      @submit="onSubmit"
+    />
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundBadges.vue b/docs/app/components/playground/PlaygroundBadges.vue
new file mode 100644
index 0000000000..d650755a60
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundBadges.vue
@@ -0,0 +1,28 @@
+<script setup lang="ts">
+const appConfig = useAppConfig()
+const extra = useStudioExtraIcons()
+</script>
+
+<template>
+  <div class="flex flex-col gap-3 p-4">
+    <div class="flex flex-wrap gap-2">
+      <UBadge label="Primary" />
+      <UBadge label="Success" color="success" variant="subtle" />
+      <UBadge label="Warning" color="warning" variant="subtle" />
+      <UBadge label="Error" color="error" variant="subtle" />
+      <UBadge label="Neutral" color="neutral" variant="outline" />
+    </div>
+
+    <div class="flex flex-wrap items-center gap-2">
+      <UBadge color="success" variant="soft" :icon="appConfig.ui.icons.success">
+        Shipped
+      </UBadge>
+      <UBadge color="warning" variant="soft" :icon="extra.clock">
+        Pending
+      </UBadge>
+      <UBadge color="neutral" variant="soft" size="lg">
+        v4.9.0
+      </UBadge>
+    </div>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundButtons.vue b/docs/app/components/playground/PlaygroundButtons.vue
new file mode 100644
index 0000000000..068b5321a6
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundButtons.vue
@@ -0,0 +1,28 @@
+<script setup lang="ts">
+const appConfig = useAppConfig()
+const extra = useStudioExtraIcons()
+</script>
+
+<template>
+  <div class="flex flex-col gap-3 p-4">
+    <div class="flex flex-wrap gap-2">
+      <UButton label="Solid" />
+      <UButton label="Outline" variant="outline" />
+      <UButton label="Soft" variant="soft" />
+      <UButton label="Subtle" variant="subtle" />
+      <UButton label="Ghost" variant="ghost" />
+    </div>
+
+    <div class="flex flex-wrap gap-2">
+      <UButton label="Get started" icon="i-lucide-rocket" color="primary" />
+      <UButton label="Loading" loading variant="outline" />
+      <UButton :icon="extra.heart" color="error" variant="soft" square aria-label="Like" />
+      <UButton :icon="extra.settings" color="neutral" variant="ghost" square aria-label="Settings" />
+    </div>
+
+    <UFieldGroup>
+      <UButton label="Copy" :icon="appConfig.ui.icons.copy" color="neutral" variant="subtle" />
+      <UButton :icon="appConfig.ui.icons.chevronDown" color="neutral" variant="subtle" square aria-label="More" />
+    </UFieldGroup>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundCalendar.vue b/docs/app/components/playground/PlaygroundCalendar.vue
new file mode 100644
index 0000000000..d8e887d915
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundCalendar.vue
@@ -0,0 +1,11 @@
+<script setup lang="ts">
+import { getLocalTimeZone, today } from '@internationalized/date'
+
+const modelValue = shallowRef(today(getLocalTimeZone()))
+</script>
+
+<template>
+  <div class="flex items-center justify-center p-4">
+    <UCalendar v-model="modelValue" :week-starts-on="1" />
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundCard.vue b/docs/app/components/playground/PlaygroundCard.vue
new file mode 100644
index 0000000000..325991c694
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundCard.vue
@@ -0,0 +1,11 @@
+<template>
+  <!-- A real UCard (no explicit variant) so the studio's panel defaults
+       and style treatments apply to the grid tiles too. Tiles bring their
+       own padding, the body slot contributes none. -->
+  <UCard
+    class="relative isolate overflow-hidden"
+    :ui="{ body: 'p-0 sm:p-0' }"
+  >
+    <slot />
+  </UCard>
+</template>
diff --git a/docs/app/components/playground/PlaygroundColorPicker.vue b/docs/app/components/playground/PlaygroundColorPicker.vue
new file mode 100644
index 0000000000..7c588ad94d
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundColorPicker.vue
@@ -0,0 +1,18 @@
+<script setup lang="ts">
+const color = ref('#00C16A')
+
+const chip = computed(() => ({ backgroundColor: color.value }))
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-4 p-4">
+    <UColorPicker v-model="color" />
+
+    <UBadge color="neutral" variant="outline" size="lg" class="font-mono">
+      <template #leading>
+        <span :style="chip" class="size-3 rounded-full" />
+      </template>
+      {{ color }}
+    </UBadge>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundCommandPalette.vue b/docs/app/components/playground/PlaygroundCommandPalette.vue
new file mode 100644
index 0000000000..3febf35edd
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundCommandPalette.vue
@@ -0,0 +1,66 @@
+<script setup lang="ts">
+const extra = useStudioExtraIcons()
+import type { CommandPaletteGroup, CommandPaletteItem } from '@nuxt/ui'
+
+const toast = useToast()
+
+const groups = ref<CommandPaletteGroup<CommandPaletteItem>[]>([
+  {
+    id: 'users',
+    label: 'Users',
+    items: [
+      {
+        label: 'Benjamin Canac',
+        suffix: 'benjamincanac',
+        avatar: { src: 'https://github.com/benjamincanac.png', loading: 'lazy' }
+      },
+      {
+        label: 'Romain Hamel',
+        suffix: 'romhml',
+        avatar: { src: 'https://github.com/romhml.png', loading: 'lazy' }
+      },
+      {
+        label: 'Neil Richter',
+        suffix: 'noook',
+        avatar: { src: 'https://github.com/noook.png', loading: 'lazy' }
+      }
+    ]
+  },
+  {
+    id: 'actions',
+    items: [
+      {
+        label: 'Add new file',
+        suffix: 'Create a new file in the current workspace.',
+        icon: extra.filePlus,
+        kbds: ['meta', 'N'],
+        onSelect() {
+          toast.add({ title: 'Add new file' })
+        }
+      },
+      {
+        label: 'Add new folder',
+        suffix: 'Create a new folder in the current workspace.',
+        icon: extra.folderPlus,
+        kbds: ['meta', 'F'],
+        onSelect() {
+          toast.add({ title: 'Add new folder' })
+        }
+      },
+      {
+        label: 'Add label',
+        suffix: 'Add a label to the current item.',
+        icon: extra.tag,
+        kbds: ['meta', 'L'],
+        onSelect() {
+          toast.add({ title: 'Add label' })
+        }
+      }
+    ]
+  }
+])
+</script>
+
+<template>
+  <UCommandPalette :groups="groups" placeholder="Search users and actions..." class="h-80" />
+</template>
diff --git a/docs/app/components/playground/PlaygroundContributors.vue b/docs/app/components/playground/PlaygroundContributors.vue
new file mode 100644
index 0000000000..4e0ea80e32
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundContributors.vue
@@ -0,0 +1,37 @@
+<script setup lang="ts">
+const usernames = [
+  'benjamincanac', 'romhml', 'noook', 'atinux', 'HugoRCD',
+  'sandros94', 'danielroe', 'J-Michalek', 'genu', 'smarroufin'
+]
+</script>
+
+<template>
+  <div class="p-4 space-y-4">
+    <div class="flex items-start justify-between">
+      <div>
+        <p class="font-semibold text-highlighted">
+          Contributors
+        </p>
+        <p class="text-sm text-muted">
+          Built by the community.
+        </p>
+      </div>
+      <UBadge color="neutral" variant="subtle">
+        312
+      </UBadge>
+    </div>
+
+    <div class="flex flex-wrap gap-1.5">
+      <UAvatar
+        v-for="username in usernames"
+        :key="username"
+        :src="`https://github.com/${username}.png`"
+        :alt="username"
+        loading="lazy"
+      />
+      <div class="flex items-center justify-center size-8 rounded-full bg-elevated text-xs font-medium text-muted">
+        +300
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundDashboard.vue b/docs/app/components/playground/PlaygroundDashboard.vue
new file mode 100644
index 0000000000..156ca0b613
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundDashboard.vue
@@ -0,0 +1,71 @@
+<script setup lang="ts">
+import type { DropdownMenuItem } from '@nuxt/ui'
+
+const toast = useToast()
+const appConfig = useAppConfig()
+const extra = useStudioExtraIcons()
+
+const items: DropdownMenuItem[][] = [
+  [
+    { label: 'View report', icon: appConfig.ui.icons.eye, onSelect: () => toast.add({ title: 'View report' }) },
+    { label: 'Export as CSV', icon: 'i-lucide-download', onSelect: () => toast.add({ title: 'Exporting…' }) },
+    { label: 'Refresh', icon: appConfig.ui.icons.reload, onSelect: () => toast.add({ title: 'Refreshed' }) }
+  ],
+  [
+    { label: 'Delete', icon: extra.trash, color: 'error', onSelect: () => toast.add({ title: 'Deleted', color: 'error' }) }
+  ]
+]
+
+const progress = ref(75)
+</script>
+
+<template>
+  <div class="flex flex-col gap-4 p-4">
+    <div class="flex items-start justify-between">
+      <div>
+        <p class="text-sm text-muted">
+          Total revenue
+        </p>
+        <p class="text-2xl font-semibold text-highlighted">
+          $48,200
+        </p>
+      </div>
+
+      <div class="flex items-center gap-2">
+        <UBadge color="success" variant="subtle" size="sm" :icon="extra.trendingUp">
+          +12.5%
+        </UBadge>
+
+        <UDropdownMenu :items="items" :ui="{ content: 'w-44' }">
+          <UButton
+            :icon="appConfig.ui.icons.ellipsis"
+            color="neutral"
+            variant="ghost"
+            size="sm"
+            square
+            aria-label="Actions"
+          />
+        </UDropdownMenu>
+      </div>
+    </div>
+
+    <div class="space-y-1.5">
+      <div class="flex items-center justify-between text-sm">
+        <span class="text-muted">Monthly goal</span>
+        <span class="font-medium text-highlighted">{{ progress }}%</span>
+      </div>
+      <UProgress v-model="progress" size="sm" />
+    </div>
+
+    <USeparator />
+
+    <div class="flex items-center justify-between">
+      <UAvatarGroup size="xs">
+        <UAvatar src="https://github.com/benjamincanac.png" alt="Benjamin Canac" loading="lazy" />
+        <UAvatar src="https://github.com/romhml.png" alt="Romain Hamel" loading="lazy" />
+        <UAvatar src="https://github.com/noook.png" alt="Neil Richter" loading="lazy" />
+      </UAvatarGroup>
+      <span class="text-xs text-muted">+8 active now</span>
+    </div>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundEmpty.vue b/docs/app/components/playground/PlaygroundEmpty.vue
new file mode 100644
index 0000000000..be0aebc227
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundEmpty.vue
@@ -0,0 +1,9 @@
+<template>
+  <UEmpty
+    icon="i-lucide-landmark"
+    title="Connect your bank"
+    description="Link your account to receive monthly payouts automatically."
+    :actions="[{ label: 'Set up payouts', icon: 'i-lucide-plug-zap' }]"
+    variant="naked"
+  />
+</template>
diff --git a/docs/app/components/playground/PlaygroundGoal.vue b/docs/app/components/playground/PlaygroundGoal.vue
new file mode 100644
index 0000000000..1ced36578e
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundGoal.vue
@@ -0,0 +1,25 @@
+<script setup lang="ts">
+const percent = 80
+
+const ring = `conic-gradient(var(--ui-primary) ${percent}%, var(--ui-bg-accented) 0)`
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-4 p-4">
+    <p class="self-start font-semibold text-highlighted">
+      Investment goal
+    </p>
+
+    <div class="relative size-32 rounded-full" :style="{ background: ring }">
+      <div class="absolute inset-3 rounded-full bg-default flex flex-col items-center justify-center">
+        <span class="text-xl font-semibold text-highlighted">$24k</span>
+        <span class="text-xs text-muted">{{ percent }}% of $30k</span>
+      </div>
+    </div>
+
+    <div class="flex items-center justify-between w-full text-sm">
+      <span class="text-muted">Projected finish</span>
+      <span class="font-medium text-highlighted">Oct 2026</span>
+    </div>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundInput.vue b/docs/app/components/playground/PlaygroundInput.vue
new file mode 100644
index 0000000000..02c1a475c9
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundInput.vue
@@ -0,0 +1,23 @@
+<script setup lang="ts">
+const appConfig = useAppConfig()
+const extra = useStudioExtraIcons()
+
+const email = ref('')
+</script>
+
+<template>
+  <div class="flex flex-col gap-4 p-4">
+    <UFormField label="Your email" description="We won't share your email." required>
+      <UInput v-model="email" type="email" placeholder="john@example.com" :icon="extra.mail" class="w-full" />
+    </UFormField>
+
+    <UFormField label="Search">
+      <UInput placeholder="Search documentation…" :icon="appConfig.ui.icons.search" :ui="{ trailing: 'gap-px' }" class="w-full">
+        <template #trailing>
+          <UKbd value="meta" />
+          <UKbd value="K" />
+        </template>
+      </UInput>
+    </UFormField>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundInviteTeam.vue b/docs/app/components/playground/PlaygroundInviteTeam.vue
new file mode 100644
index 0000000000..3422cf9e9e
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundInviteTeam.vue
@@ -0,0 +1,57 @@
+<script setup lang="ts">
+const appConfig = useAppConfig()
+const toast = useToast()
+
+const roles = [
+  { label: 'Editor', value: 'editor' },
+  { label: 'Viewer', value: 'viewer' }
+]
+
+const members = ref([
+  { email: 'alex@example.com', role: 'editor' },
+  { email: 'sam@example.com', role: 'viewer' }
+])
+
+const link = 'https://app.nuxt.com/invite/x8f2k'
+</script>
+
+<template>
+  <div>
+    <div class="p-4 space-y-4">
+      <div>
+        <p class="font-semibold text-highlighted">
+          Invite your team
+        </p>
+        <p class="text-sm text-muted">
+          Add members to your workspace.
+        </p>
+      </div>
+
+      <div class="space-y-2">
+        <div v-for="(member, index) in members" :key="index" class="flex items-center gap-2">
+          <UInput v-model="member.email" type="email" class="flex-1" />
+          <USelect v-model="member.role" :items="roles" class="w-28" />
+        </div>
+      </div>
+
+      <USeparator label="Or share a link" />
+
+      <UInput :model-value="link" readonly class="w-full">
+        <template #trailing>
+          <UButton
+            :icon="appConfig.ui.icons.copy"
+            color="neutral"
+            variant="link"
+            size="xs"
+            aria-label="Copy link"
+            @click="toast.add({ title: 'Invite link copied' })"
+          />
+        </template>
+      </UInput>
+    </div>
+
+    <div class="flex justify-end border-t border-default p-3">
+      <UButton label="Send invites" @click="toast.add({ title: 'Invites sent' })" />
+    </div>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundNavigation.vue b/docs/app/components/playground/PlaygroundNavigation.vue
new file mode 100644
index 0000000000..ee4db9fed6
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundNavigation.vue
@@ -0,0 +1,25 @@
+<script setup lang="ts">
+import type { NavigationMenuItem } from '@nuxt/ui'
+
+const appConfig = useAppConfig()
+const extra = useStudioExtraIcons()
+
+const items: NavigationMenuItem[][] = [
+  [
+    { label: 'Dashboard', icon: 'i-lucide-layout-dashboard', active: true },
+    { label: 'Inbox', icon: extra.inbox, badge: '4' },
+    { label: 'Projects', icon: appConfig.ui.icons.folder },
+    { label: 'Calendar', icon: extra.calendar }
+  ],
+  [
+    { label: 'Settings', icon: extra.settings },
+    { label: 'Help', icon: appConfig.ui.icons.info }
+  ]
+]
+</script>
+
+<template>
+  <div class="p-2">
+    <UNavigationMenu orientation="vertical" :items="items" class="w-full" />
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundNotifications.vue b/docs/app/components/playground/PlaygroundNotifications.vue
new file mode 100644
index 0000000000..6dca00a59a
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundNotifications.vue
@@ -0,0 +1,34 @@
+<script setup lang="ts">
+const toast = useToast()
+
+const settings = ref({
+  transactions: true,
+  security: true,
+  marketing: false
+})
+</script>
+
+<template>
+  <div>
+    <div class="p-4 space-y-4">
+      <div>
+        <p class="font-semibold text-highlighted">
+          Notifications
+        </p>
+        <p class="text-sm text-muted">
+          Choose what you want to be notified about.
+        </p>
+      </div>
+
+      <div class="space-y-3">
+        <USwitch v-model="settings.transactions" label="Transaction alerts" description="Deposits, withdrawals and transfers." />
+        <USwitch v-model="settings.security" label="Security alerts" description="Login attempts and account changes." />
+        <USwitch v-model="settings.marketing" label="Marketing emails" description="Product news and occasional updates." />
+      </div>
+    </div>
+
+    <div class="flex justify-end border-t border-default p-3">
+      <UButton label="Save preferences" @click="toast.add({ title: 'Preferences saved' })" />
+    </div>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundPinInput.vue b/docs/app/components/playground/PlaygroundPinInput.vue
new file mode 100644
index 0000000000..56fa920d00
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundPinInput.vue
@@ -0,0 +1,24 @@
+<script setup lang="ts">
+const value = ref<string[]>(['4', '3', '2'])
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-3 p-6 text-center">
+    <UIcon name="i-lucide-shield-check" class="size-7 text-primary" />
+
+    <div>
+      <p class="font-semibold text-highlighted">
+        Verify your account
+      </p>
+      <p class="text-sm text-muted">
+        Enter the 6-digit code we sent you.
+      </p>
+    </div>
+
+    <UPinInput v-model="value" :length="6" otp :separator="3" />
+
+    <p class="text-sm text-muted">
+      Didn't get a code? <UButton variant="link" class="p-0" label="Resend" />
+    </p>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundPrompt.vue b/docs/app/components/playground/PlaygroundPrompt.vue
new file mode 100644
index 0000000000..047300e1d6
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundPrompt.vue
@@ -0,0 +1,229 @@
+<script setup lang="ts">
+import type { DropdownMenuItem } from '@nuxt/ui'
+
+const appConfig = useAppConfig()
+const extra = useStudioExtraIcons()
+
+const toast = useToast()
+
+const input = ref('')
+const awsMarketplace = ref(true)
+const claudeInChrome = ref(true)
+const webSearch = ref(true)
+
+const models = [
+  { value: 'opus-5', label: 'Opus 5', description: 'Deep reasoning and hard problems' },
+  { value: 'sonnet-5', label: 'Sonnet 5', description: 'Balanced speed and intelligence' },
+  { value: 'haiku-4-5', label: 'Haiku 4.5', description: 'Fastest for everyday tasks' }
+]
+const legacyModels = [
+  { value: 'opus-4-8', label: 'Opus 4.8' },
+  { value: 'sonnet-4-6', label: 'Sonnet 4.6' }
+]
+const efforts = ['Low', 'Medium', 'High', 'Max']
+
+const model = ref('opus-5')
+const effort = ref('High')
+
+const activeModel = computed(() => [...models, ...legacyModels].find(m => m.value === model.value))
+
+const modelItems = computed<DropdownMenuItem[][]>(() => [
+  models.map(m => ({
+    label: m.label,
+    description: m.description,
+    type: 'checkbox',
+    checked: model.value === m.value,
+    onUpdateChecked() {
+      model.value = m.value
+    }
+  })),
+  [
+    {
+      label: 'Legacy models',
+      icon: extra.clock,
+      children: legacyModels.map(m => ({
+        label: m.label,
+        type: 'checkbox',
+        checked: model.value === m.value,
+        onUpdateChecked() {
+          model.value = m.value
+        }
+      }))
+    },
+    {
+      label: 'Effort',
+      icon: extra.zap,
+      slot: 'effort',
+      children: efforts.map(e => ({
+        label: e,
+        type: 'checkbox',
+        checked: effort.value === e,
+        onUpdateChecked() {
+          effort.value = e
+        }
+      }))
+    }
+  ]
+])
+
+const items = computed<DropdownMenuItem[][]>(() => [
+  [
+    { label: 'Add files or photos', icon: extra.paperclip, kbds: ['meta', 'U'] },
+    {
+      label: 'Add to project',
+      icon: appConfig.ui.icons.folder,
+      children: [
+        { label: 'New project', icon: appConfig.ui.icons.plus },
+        { label: 'Nuxt UI', icon: appConfig.ui.icons.folder }
+      ]
+    }
+  ],
+  [
+    {
+      label: 'Skills',
+      icon: 'i-lucide-shapes',
+      children: [
+        { label: 'Canvas design', icon: extra.palette },
+        { label: 'Slides', icon: 'i-lucide-presentation' },
+        { label: 'PDF', icon: appConfig.ui.icons.file }
+      ]
+    },
+    {
+      label: 'Connectors',
+      icon: 'i-lucide-blocks',
+      children: [
+        [
+          { label: 'Add connector', icon: appConfig.ui.icons.plus },
+          { label: 'Manage connectors', icon: extra.briefcase }
+        ],
+        [
+          {
+            label: 'AWS Marketplace',
+            icon: 'i-simple-icons-amazon',
+            slot: 'switch',
+            checked: awsMarketplace.value,
+            onSelect(e: Event) {
+              e.preventDefault()
+              awsMarketplace.value = !awsMarketplace.value
+            }
+          },
+          {
+            label: 'Claude in Chrome',
+            icon: 'i-simple-icons-googlechrome',
+            slot: 'switch',
+            checked: claudeInChrome.value,
+            onSelect(e: Event) {
+              e.preventDefault()
+              claudeInChrome.value = !claudeInChrome.value
+            }
+          }
+        ],
+        [
+          { label: 'Tool access', icon: appConfig.ui.icons.search }
+        ]
+      ]
+    },
+    { label: 'Add plugins…', icon: 'i-lucide-plug' }
+  ],
+  [
+    { label: 'Ask Vercel', icon: 'i-simple-icons-vercel' },
+    { label: 'Research', icon: 'i-lucide-activity' },
+    {
+      label: 'Web search',
+      icon: extra.globe,
+      type: 'checkbox',
+      checked: webSearch.value,
+      onUpdateChecked(checked: boolean) {
+        webSearch.value = checked
+      }
+    }
+  ]
+])
+
+function onSubmit() {
+  if (!input.value.trim()) return
+
+  toast.add({ title: 'Message sent', description: input.value })
+  input.value = ''
+}
+</script>
+
+<template>
+  <UChatPrompt
+    v-model="input"
+    variant="naked"
+    size="md"
+    :rows="3"
+    autoresize
+    :autofocus="false"
+    placeholder="Paste a doc, an email, or a question to get started"
+    :ui="{ root: 'rounded-none p-2.5', body: 'p-1.5', base: 'px-0' }"
+    @submit="onSubmit"
+  >
+    <template #footer>
+      <div class="flex items-center justify-between gap-2 w-full">
+        <div class="flex items-center gap-1">
+          <UDropdownMenu :items="items" :content="{ align: 'start', side: 'top' }" :ui="{ content: 'w-60' }" size="sm">
+            <UButton
+              :icon="appConfig.ui.icons.plus"
+              color="neutral"
+              variant="ghost"
+              size="sm"
+              square
+              aria-label="Add content"
+            />
+
+            <template #switch-trailing="{ item }">
+              <USwitch :model-value="(item as DropdownMenuItem).checked" size="sm" tabindex="-1" />
+            </template>
+          </UDropdownMenu>
+
+          <UDropdownMenu :items="modelItems" :content="{ align: 'start', side: 'top' }" :ui="{ content: 'w-72' }" size="sm">
+            <UButton
+              color="neutral"
+              variant="ghost"
+              size="sm"
+              :trailing-icon="appConfig.ui.icons.chevronDown"
+              class="group"
+              :ui="{ trailingIcon: 'group-data-[state=open]:rotate-180 transition-transform duration-200' }"
+            >
+              {{ activeModel?.label }} <span class="text-dimmed">{{ effort }}</span>
+            </UButton>
+
+            <template #effort-trailing="{ ui }">
+              <span class="text-dimmed">{{ effort }}</span>
+              <UIcon :name="appConfig.ui.icons.chevronRight" :class="ui.itemTrailingIcon()" />
+            </template>
+          </UDropdownMenu>
+        </div>
+
+        <div class="flex items-center gap-1">
+          <UButton
+            :icon="extra.mic"
+            color="neutral"
+            variant="ghost"
+            size="sm"
+            square
+            aria-label="Dictate"
+          />
+          <UButton
+            icon="i-lucide-audio-lines"
+            color="neutral"
+            variant="ghost"
+            size="sm"
+            square
+            aria-label="Voice mode"
+          />
+          <UButton
+            :icon="appConfig.ui.icons.arrowUp"
+            color="primary"
+            size="sm"
+            square
+            aria-label="Send"
+            @click="onSubmit"
+          />
+        </div>
+      </div>
+    </template>
+  </UChatPrompt>
+</template>
diff --git a/docs/app/components/playground/PlaygroundReportBug.vue b/docs/app/components/playground/PlaygroundReportBug.vue
new file mode 100644
index 0000000000..42c13d3743
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundReportBug.vue
@@ -0,0 +1,58 @@
+<script setup lang="ts">
+const toast = useToast()
+const extra = useStudioExtraIcons()
+
+const severities = [
+  { label: 'Low', value: 'low' },
+  { label: 'Medium', value: 'medium' },
+  { label: 'High', value: 'high' }
+]
+
+const components = [
+  { label: 'Dashboard', value: 'dashboard' },
+  { label: 'API', value: 'api' },
+  { label: 'Billing', value: 'billing' }
+]
+
+const title = ref('')
+const severity = ref('medium')
+const component = ref('dashboard')
+const steps = ref('')
+</script>
+
+<template>
+  <div>
+    <div class="p-4 space-y-4">
+      <div>
+        <p class="font-semibold text-highlighted">
+          Report a bug
+        </p>
+        <p class="text-sm text-muted">
+          Help us fix issues faster.
+        </p>
+      </div>
+
+      <UFormField label="Title">
+        <UInput v-model="title" placeholder="Brief description of the issue" class="w-full" />
+      </UFormField>
+
+      <div class="grid grid-cols-2 gap-3">
+        <UFormField label="Severity">
+          <USelect v-model="severity" :items="severities" class="w-full" />
+        </UFormField>
+        <UFormField label="Component">
+          <USelect v-model="component" :items="components" class="w-full" />
+        </UFormField>
+      </div>
+
+      <UFormField label="Steps to reproduce">
+        <UTextarea v-model="steps" :rows="3" placeholder="1. Go to… 2. Click on… 3. See error" class="w-full" />
+      </UFormField>
+    </div>
+
+    <div class="flex items-center justify-between border-t border-default p-3">
+      <UButton label="Attach file" :icon="extra.paperclip" color="neutral" variant="ghost" />
+      <UButton label="Submit bug" @click="toast.add({ title: 'Bug reported' })" />
+    </div>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundSavingsTargets.vue b/docs/app/components/playground/PlaygroundSavingsTargets.vue
new file mode 100644
index 0000000000..214e04d92b
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundSavingsTargets.vue
@@ -0,0 +1,30 @@
+<script setup lang="ts">
+const targets = [
+  { label: 'Retirement', amount: '$420,000', value: 65 },
+  { label: 'Real estate', amount: '$85,000', value: 32 }
+]
+</script>
+
+<template>
+  <div class="p-4 space-y-4">
+    <div>
+      <p class="font-semibold text-highlighted">
+        Savings targets
+      </p>
+      <p class="text-sm text-muted">
+        Active milestones for 2026.
+      </p>
+    </div>
+
+    <div v-for="target in targets" :key="target.label" class="space-y-2">
+      <div class="flex items-baseline justify-between">
+        <span class="text-xs uppercase tracking-wide text-muted">{{ target.label }}</span>
+        <span class="text-xs text-muted">{{ target.value }}% achieved</span>
+      </div>
+      <p class="text-xl font-semibold text-highlighted">
+        {{ target.amount }}
+      </p>
+      <UProgress :model-value="target.value" size="sm" />
+    </div>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundShortcuts.vue b/docs/app/components/playground/PlaygroundShortcuts.vue
new file mode 100644
index 0000000000..c997147de1
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundShortcuts.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+const shortcuts = [
+  { label: 'Search', keys: ['meta', 'K'] },
+  { label: 'Quick actions', keys: ['meta', 'J'] },
+  { label: 'New file', keys: ['meta', 'N'] },
+  { label: 'Save', keys: ['meta', 'S'] },
+  { label: 'Toggle sidebar', keys: ['meta', 'B'] }
+]
+</script>
+
+<template>
+  <div>
+    <div class="p-4">
+      <p class="font-semibold text-highlighted">
+        Shortcuts
+      </p>
+      <p class="text-sm text-muted">
+        Work faster with the keyboard.
+      </p>
+    </div>
+
+    <USeparator />
+
+    <ul class="divide-y divide-default">
+      <li v-for="shortcut in shortcuts" :key="shortcut.label" class="flex items-center justify-between px-4 py-2.5">
+        <span class="text-sm text-default">{{ shortcut.label }}</span>
+        <div class="flex gap-1">
+          <UKbd v-for="key in shortcut.keys" :key="key" :value="key" />
+        </div>
+      </li>
+    </ul>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundTabs.vue b/docs/app/components/playground/PlaygroundTabs.vue
new file mode 100644
index 0000000000..9c1b3f7297
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundTabs.vue
@@ -0,0 +1,51 @@
+<script setup lang="ts">
+const extra = useStudioExtraIcons()
+
+const items = [
+  {
+    label: 'Account',
+    icon: extra.user,
+    slot: 'account'
+  },
+  {
+    label: 'Password',
+    icon: extra.lock,
+    slot: 'password'
+  }
+]
+
+const state = reactive({
+  name: 'Benjamin Canac',
+  username: 'benjamincanac',
+  currentPassword: '',
+  newPassword: ''
+})
+</script>
+
+<template>
+  <div class="p-4">
+    <UTabs :items="items" class="w-full">
+      <template #account>
+        <UForm :state="state" class="flex flex-col gap-4">
+          <UFormField label="Name" name="name">
+            <UInput v-model="state.name" class="w-full" />
+          </UFormField>
+          <UFormField label="Username" name="username">
+            <UInput v-model="state.username" class="w-full" />
+          </UFormField>
+        </UForm>
+      </template>
+
+      <template #password>
+        <UForm :state="state" class="flex flex-col gap-4">
+          <UFormField label="Current Password" name="current" required>
+            <UInput v-model="state.currentPassword" type="password" required class="w-full" />
+          </UFormField>
+          <UFormField label="New Password" name="new" required>
+            <UInput v-model="state.newPassword" type="password" required class="w-full" />
+          </UFormField>
+        </UForm>
+      </template>
+    </UTabs>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundTransactions.vue b/docs/app/components/playground/PlaygroundTransactions.vue
new file mode 100644
index 0000000000..5cbf87a954
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundTransactions.vue
@@ -0,0 +1,48 @@
+<script setup lang="ts">
+const extra = useStudioExtraIcons()
+
+const transactions = [
+  { name: 'Stripe Payout', category: 'Income', icon: 'i-lucide-arrow-down-left', amount: 2400.00 },
+  { name: 'Blue Bottle Coffee', category: 'Food & Drink', icon: extra.coffee, amount: -8.50 },
+  { name: 'Whole Foods Market', category: 'Groceries', icon: extra.cart, amount: -64.20 },
+  { name: 'Netflix', category: 'Entertainment', icon: extra.movie, amount: -19.99 }
+]
+
+function format(amount: number) {
+  return `${amount < 0 ? '-' : '+'}$${Math.abs(amount).toFixed(2)}`
+}
+</script>
+
+<template>
+  <div>
+    <div class="p-4">
+      <p class="font-semibold text-highlighted">
+        Recent transactions
+      </p>
+      <p class="text-sm text-muted">
+        Your latest account activity.
+      </p>
+    </div>
+
+    <USeparator />
+
+    <ul class="divide-y divide-default">
+      <li v-for="transaction in transactions" :key="transaction.name" class="flex items-center gap-3 px-4 py-2.5">
+        <div class="flex items-center justify-center size-8 rounded-full bg-elevated text-muted shrink-0">
+          <UIcon :name="transaction.icon" class="size-4" />
+        </div>
+        <div class="min-w-0 flex-1">
+          <p class="text-sm font-medium text-highlighted truncate">
+            {{ transaction.name }}
+          </p>
+          <p class="text-xs text-muted truncate">
+            {{ transaction.category }}
+          </p>
+        </div>
+        <span class="text-sm font-medium" :class="transaction.amount < 0 ? 'text-highlighted' : 'text-success'">
+          {{ format(transaction.amount) }}
+        </span>
+      </li>
+    </ul>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundTransferFunds.vue b/docs/app/components/playground/PlaygroundTransferFunds.vue
new file mode 100644
index 0000000000..a936f02013
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundTransferFunds.vue
@@ -0,0 +1,54 @@
+<script setup lang="ts">
+const toast = useToast()
+
+const accounts = [
+  { label: 'Main Checking •8402', value: 'checking' },
+  { label: 'High Yield Savings •1192', value: 'savings' }
+]
+
+const amount = ref(1200)
+const from = ref('checking')
+const to = ref('savings')
+</script>
+
+<template>
+  <div>
+    <div class="p-4 space-y-4">
+      <div>
+        <p class="font-semibold text-highlighted">
+          Transfer funds
+        </p>
+        <p class="text-sm text-muted">
+          Move money between your accounts.
+        </p>
+      </div>
+
+      <UFormField label="Amount">
+        <UInputNumber v-model="amount" :format-options="{ style: 'currency', currency: 'USD' }" class="w-full" />
+      </UFormField>
+
+      <UFormField label="From">
+        <USelect v-model="from" :items="accounts" class="w-full" />
+      </UFormField>
+
+      <UFormField label="To">
+        <USelect v-model="to" :items="accounts" class="w-full" />
+      </UFormField>
+
+      <div class="space-y-1.5 text-sm">
+        <div class="flex justify-between">
+          <span class="text-muted">Estimated arrival</span>
+          <span class="font-medium text-highlighted">Today</span>
+        </div>
+        <div class="flex justify-between">
+          <span class="text-muted">Transaction fee</span>
+          <span class="font-medium text-highlighted">$0.00</span>
+        </div>
+      </div>
+    </div>
+
+    <div class="flex justify-end border-t border-default p-3">
+      <UButton label="Confirm transfer" @click="toast.add({ title: 'Transfer confirmed' })" />
+    </div>
+  </div>
+</template>
diff --git a/docs/app/components/playground/PlaygroundTypography.vue b/docs/app/components/playground/PlaygroundTypography.vue
new file mode 100644
index 0000000000..ddc6c3fe52
--- /dev/null
+++ b/docs/app/components/playground/PlaygroundTypography.vue
@@ -0,0 +1,31 @@
+<template>
+  <div class="p-4 space-y-3">
+    <p class="text-xs uppercase tracking-widest text-muted">
+      Type scale
+    </p>
+
+    <h3 class="text-xl font-semibold text-highlighted leading-tight">
+      Designing with rhythm &amp; hierarchy
+    </h3>
+
+    <p class="text-sm text-muted leading-relaxed">
+      A strong body style keeps long-form content readable and balances the visual weight of headings.
+    </p>
+
+    <div class="flex items-baseline justify-between text-highlighted pt-1">
+      <span class="font-light">Light</span>
+      <span class="font-normal">Regular</span>
+      <span class="font-medium">Medium</span>
+      <span class="font-semibold">Semibold</span>
+      <span class="font-bold">Bold</span>
+    </div>
+
+    <div class="flex gap-1.5 pt-1">
+      <span class="size-6 rounded-md bg-primary" />
+      <span class="size-6 rounded-md bg-elevated" />
+      <span class="size-6 rounded-md bg-accented" />
+      <span class="size-6 rounded-md bg-inverted" />
+      <span class="size-6 rounded-md ring ring-default" />
+    </div>
+  </div>
+</template>
diff --git a/docs/app/components/theme-picker/ThemePicker.vue b/docs/app/components/theme-picker/ThemePicker.vue
deleted file mode 100644
index badfc7b9f7..0000000000
--- a/docs/app/components/theme-picker/ThemePicker.vue
+++ /dev/null
@@ -1,267 +0,0 @@
-<script setup lang="ts">
-const colorMode = useColorMode()
-const { track } = useAnalytics()
-
-const open = ref(false)
-
-watch(open, (isOpen) => {
-  if (isOpen) {
-    track('Theme Picker Opened')
-  }
-})
-
-const { copy: copyCSS, copied: copiedCSS } = useClipboard()
-const { copy: copyConfig, copied: copiedConfig } = useClipboard()
-
-const {
-  neutralColors,
-  neutral,
-  primaryColors,
-  primary,
-  blackAsPrimary,
-  setBlackAsPrimary,
-  radiuses,
-  radius,
-  fonts,
-  font,
-  icon,
-  icons,
-  modes,
-  mode,
-  hasCSSChanges,
-  hasConfigChanges,
-  configLabel,
-  exportCSS,
-  exportConfig,
-  resetTheme
-} = useTheme()
-</script>
-
-<template>
-  <UPopover v-model:open="open" :ui="{ content: 'w-72 px-6 py-4 flex flex-col gap-4 overflow-y-auto max-h-[calc(100vh-5rem)]' }">
-    <template #default>
-      <UButton
-        icon="i-lucide-swatch-book"
-        color="neutral"
-        :variant="open ? 'soft' : 'ghost'"
-        square
-        aria-label="Color picker"
-        :ui="{ leadingIcon: 'text-primary' }"
-      />
-    </template>
-
-    <template #content>
-      <fieldset>
-        <legend class="text-[11px] leading-none font-semibold mb-2 select-none flex items-center gap-1">
-          Primary
-
-          <UButton
-            to="/docs/getting-started/theme/css-variables#colors"
-            size="xs"
-            color="neutral"
-            variant="link"
-            icon="i-lucide-help-circle"
-            class="p-0 -my-0.5"
-            :ui="{ leadingIcon: 'size-3' }"
-          />
-        </legend>
-
-        <div class="grid grid-cols-3 gap-1 -mx-2">
-          <ThemePickerButton
-            label="Black"
-            :selected="blackAsPrimary"
-            @click="setBlackAsPrimary(true)"
-          >
-            <template #leading>
-              <span class="inline-block size-2 rounded-full bg-black dark:bg-white" />
-            </template>
-          </ThemePickerButton>
-
-          <ThemePickerButton
-            v-for="color in primaryColors"
-            :key="color"
-            :label="color"
-            :chip="color"
-            :selected="!blackAsPrimary && primary === color"
-            @click="primary = color"
-          />
-        </div>
-      </fieldset>
-
-      <fieldset>
-        <legend class="text-[11px] leading-none font-semibold mb-2 select-none flex items-center gap-1">
-          Neutral
-
-          <UButton
-            to="/docs/getting-started/theme/css-variables#text"
-            size="xs"
-            color="neutral"
-            variant="link"
-            icon="i-lucide-help-circle"
-            class="p-0 -my-0.5"
-            :ui="{ leadingIcon: 'size-3' }"
-          />
-        </legend>
-
-        <div class="grid grid-cols-3 gap-1 -mx-2">
-          <ThemePickerButton
-            v-for="color in neutralColors"
-            :key="color"
-            :label="color"
-            :chip="color === 'neutral' ? 'old-neutral' : color"
-            :selected="neutral === color"
-            @click="neutral = color"
-          />
-        </div>
-      </fieldset>
-
-      <fieldset>
-        <legend class="text-[11px] leading-none font-semibold mb-2 select-none flex items-center gap-1">
-          Radius
-
-          <UButton
-            to="/docs/getting-started/theme/css-variables#radius"
-            size="xs"
-            color="neutral"
-            variant="link"
-            icon="i-lucide-help-circle"
-            class="p-0 -my-0.5"
-            :ui="{ leadingIcon: 'size-3' }"
-          />
-        </legend>
-
-        <div class="grid grid-cols-5 gap-1 -mx-2">
-          <ThemePickerButton
-            v-for="r in radiuses"
-            :key="r"
-            :label="String(r)"
-            class="justify-center px-0"
-            :selected="radius === r"
-            @click="radius = r"
-          />
-        </div>
-      </fieldset>
-
-      <fieldset>
-        <legend class="text-[11px] leading-none font-semibold mb-2 select-none flex items-center gap-1">
-          Font
-
-          <UButton
-            to="/docs/getting-started/integrations/fonts"
-            size="xs"
-            color="neutral"
-            variant="link"
-            icon="i-lucide-help-circle"
-            class="p-0 -my-0.5"
-            :ui="{ leadingIcon: 'size-3' }"
-          />
-        </legend>
-
-        <div class="-mx-2">
-          <USelect
-            v-model="font"
-            size="sm"
-            color="neutral"
-            icon="i-lucide-type"
-            :items="fonts"
-            class="w-full ring-default rounded-sm hover:bg-elevated/50 text-[11px] data-[state=open]:bg-elevated/50"
-            :ui="{ trailingIcon: 'group-data-[state=open]:rotate-180 transition-transform duration-200' }"
-          />
-        </div>
-      </fieldset>
-
-      <fieldset>
-        <legend class="text-[11px] leading-none font-semibold mb-2 select-none flex items-center gap-1">
-          Icons
-
-          <UButton
-            to="/docs/getting-started/integrations/icons"
-            size="xs"
-            color="neutral"
-            variant="link"
-            icon="i-lucide-help-circle"
-            class="p-0 -my-0.5"
-            :ui="{ leadingIcon: 'size-3' }"
-          />
-        </legend>
-
-        <div class="-mx-2">
-          <USelect
-            v-model="icon"
-            size="sm"
-            color="neutral"
-            :icon="icons.find(i => i.value === icon)?.icon"
-            :items="icons"
-            class="w-full ring-default rounded-sm hover:bg-elevated/50 capitalize text-[11px] data-[state=open]:bg-elevated/50"
-            :ui="{ item: 'capitalize text-[11px]', trailingIcon: 'group-data-[state=open]:rotate-180 transition-transform duration-200' }"
-          />
-        </div>
-      </fieldset>
-
-      <fieldset>
-        <legend class="text-[11px] leading-none font-semibold mb-2 select-none flex items-center gap-1">
-          Color Mode
-
-          <UButton
-            to="/docs/getting-started/integrations/color-mode"
-            size="xs"
-            color="neutral"
-            variant="link"
-            icon="i-lucide-help-circle"
-            class="p-0 -my-0.5"
-            :ui="{ leadingIcon: 'size-3' }"
-          />
-        </legend>
-
-        <div class="grid grid-cols-3 gap-1 -mx-2">
-          <ThemePickerButton
-            v-for="m in modes"
-            :key="m.label"
-            v-bind="m"
-            :selected="colorMode.preference === m.label"
-            @click="mode = m.label"
-          />
-        </div>
-      </fieldset>
-
-      <fieldset v-if="hasCSSChanges || hasConfigChanges">
-        <legend class="text-[11px] leading-none font-semibold mb-2 select-none">
-          Export
-        </legend>
-
-        <div class="flex items-center justify-between gap-1 -mx-2">
-          <UButton
-            v-if="hasCSSChanges"
-            color="neutral"
-            variant="soft"
-            size="sm"
-            label="main.css"
-            class="flex-1 text-[11px]"
-            :icon="copiedCSS ? 'i-lucide-copy-check' : 'i-lucide-copy'"
-            @click="copyCSS(exportCSS())"
-          />
-          <UButton
-            v-if="hasConfigChanges"
-            color="neutral"
-            variant="soft"
-            size="sm"
-            :label="configLabel"
-            :icon="copiedConfig ? 'i-lucide-copy-check' : 'i-lucide-copy'"
-            class="flex-1 text-[11px]"
-            @click="copyConfig(exportConfig())"
-          />
-          <UTooltip text="Reset theme">
-            <UButton
-              color="neutral"
-              variant="outline"
-              size="sm"
-              icon="i-lucide-rotate-ccw"
-              class="ms-auto ring-default hover:bg-elevated/50"
-              @click="resetTheme"
-            />
-          </UTooltip>
-        </div>
-      </fieldset>
-    </template>
-  </UPopover>
-</template>
diff --git a/docs/app/components/theme-picker/ThemePickerButton.vue b/docs/app/components/theme-picker/ThemePickerButton.vue
deleted file mode 100644
index 8795cf891a..0000000000
--- a/docs/app/components/theme-picker/ThemePickerButton.vue
+++ /dev/null
@@ -1,37 +0,0 @@
-<script setup lang="ts">
-defineProps<{
-  label: string
-  icon?: string
-  chip?: string
-  selected?: boolean
-}>()
-
-const slots = defineSlots<{
-  leading: () => any
-}>()
-</script>
-
-<template>
-  <UButton
-    size="sm"
-    color="neutral"
-    variant="outline"
-    :icon="icon"
-    :label="label"
-    class="capitalize ring-default rounded-sm text-[11px]"
-    :class="[selected ? 'bg-elevated' : 'hover:bg-elevated/50']"
-  >
-    <template v-if="chip || !!slots.leading" #leading>
-      <slot name="leading">
-        <span
-          class="inline-block size-2 rounded-full"
-          :class="`bg-(--color-light) dark:bg-(--color-dark)`"
-          :style="{
-            '--color-light': `var(--color-${chip}-500)`,
-            '--color-dark': `var(--color-${chip}-400)`
-          }"
-        />
-      </slot>
-    </template>
-  </UButton>
-</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioActionToggle.vue b/docs/app/components/theme-studio/ThemeStudioActionToggle.vue
new file mode 100644
index 0000000000..1ae76d426c
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioActionToggle.vue
@@ -0,0 +1,26 @@
+<script setup lang="ts">
+/** A section header's fold-out toggle: ghost until on, tinted while open. */
+defineProps<{
+  icon: string
+  tooltip: string
+  ariaLabel?: string
+}>()
+
+const open = defineModel<boolean>({ default: false })
+</script>
+
+<template>
+  <UTooltip :text="tooltip">
+    <UButton
+      :icon="icon"
+      color="neutral"
+      variant="ghost"
+      size="sm"
+      :active="open"
+      active-color="primary"
+      active-variant="subtle"
+      :aria-label="ariaLabel"
+      @click="open = !open"
+    />
+  </UTooltip>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioColorMenu.vue b/docs/app/components/theme-studio/ThemeStudioColorMenu.vue
new file mode 100644
index 0000000000..2e826f54da
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioColorMenu.vue
@@ -0,0 +1,118 @@
+<script setup lang="ts">
+import type { ColorAlias } from '../../utils/theme/engine'
+import { paletteLabel } from '../../utils/theme/studio'
+
+/**
+ * The shared color picker: a swatch-labelled trigger opening the palette
+ * grid. Everything derives from the alias, so the studio sidebar and the
+ * header popover render the exact same picker.
+ */
+const props = defineProps<{ alias: ColorAlias }>()
+
+const appConfig = useAppConfig()
+const { neutralColors, primaryColors, primary, neutral, blackAsPrimary, setBlackAsPrimary } = useTheme()
+const { selectPalette, isCustomPalette } = useThemeStudio()
+
+// Strictly separated for v4: color roles offer only chromatic ramps, the
+// neutral role only gray ramps, the module's shade recipes differ per
+// role, so a ramp can't cross over faithfully until v5.
+const colors = computed(() => props.alias === 'neutral' ? neutralColors : primaryColors)
+
+const value = computed(() => {
+  if (props.alias === 'primary') return blackAsPrimary.value ? 'black' : primary.value
+  if (props.alias === 'neutral') return neutral.value
+  return (appConfig.ui.colors as Record<string, string>)[props.alias] || props.alias
+})
+
+const label = computed(() => {
+  if (props.alias === 'primary' && blackAsPrimary.value) return 'Black'
+  return isCustomPalette(props.alias) ? 'Custom' : paletteLabel(value.value)
+})
+
+/** Palette name → the css var chip name (tailwind's neutral gray is remapped in docs). */
+function paletteChip(name: string) {
+  return name === 'neutral' ? 'old-neutral' : name
+}
+
+const swatchColor = computed(() => {
+  if (props.alias === 'primary' && blackAsPrimary.value) return undefined
+  if (isCustomPalette(props.alias)) return `var(--color-custom-${props.alias}-500)`
+  return `var(--color-${paletteChip(value.value)}-500)`
+})
+
+function isSelected(color: string) {
+  if (props.alias === 'primary') return !blackAsPrimary.value && primary.value === color
+  if (props.alias === 'neutral') return neutral.value === color
+  return value.value === color
+}
+</script>
+
+<template>
+  <UPopover :content="{ side: 'bottom', align: 'start' }">
+    <UButton
+      color="neutral"
+      variant="subtle"
+      size="sm"
+      block
+      trailing-icon="i-lucide-chevron-down"
+      class="capitalize"
+    >
+      <template #leading>
+        <span
+          class="inline-block size-3 rounded-full"
+          :class="{ 'bg-black dark:bg-white': alias === 'primary' && blackAsPrimary }"
+          :style="swatchColor ? { backgroundColor: swatchColor } : undefined"
+        />
+      </template>
+
+      {{ label }}
+    </UButton>
+
+    <template #content>
+      <div class="w-72 p-2">
+        <div class="grid grid-cols-3 gap-1">
+          <UButton
+            v-if="alias === 'primary'"
+            label="Black"
+            size="sm"
+            color="neutral"
+            variant="subtle"
+            :active="blackAsPrimary"
+            active-color="primary"
+            active-variant="subtle"
+            class="capitalize"
+            @click="setBlackAsPrimary(true)"
+          >
+            <template #leading>
+              <span class="inline-block h-2 w-4 rounded-full bg-black dark:bg-white" />
+            </template>
+          </UButton>
+
+          <UButton
+            v-for="color in colors"
+            :key="color"
+            :label="paletteLabel(color)"
+            size="sm"
+            color="neutral"
+            variant="subtle"
+            :active="isSelected(color)"
+            active-color="primary"
+            active-variant="subtle"
+            class="capitalize"
+            @click="selectPalette(alias, color)"
+          >
+            <template #leading>
+              <!-- a mini 400→600 ramp says more about a palette than one dot -->
+              <span
+                class="inline-block h-2 w-4 rounded-full"
+                :style="{
+                  background: `linear-gradient(to right, var(--color-${paletteChip(color)}-400), var(--color-${paletteChip(color)}-500), var(--color-${paletteChip(color)}-600))`
+                }"
+              />
+            </template>
+          </UButton>
+        </div>
+      </div>
+    </template>
+  </UPopover>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioColorSection.vue b/docs/app/components/theme-studio/ThemeStudioColorSection.vue
new file mode 100644
index 0000000000..b27d789548
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioColorSection.vue
@@ -0,0 +1,74 @@
+<script setup lang="ts">
+import type { ColorAlias, SectionKey } from '../../utils/theme/engine'
+
+/**
+ * One color alias: its picker, with the palette and shade editors folding out
+ * under it. Aliases expose their accent pair; neutral its every token group.
+ */
+const props = withDefaults(defineProps<{
+  alias: ColorAlias
+  /** Header text, defaults to the capitalized alias. */
+  label?: string
+  helpTo?: string
+  /** Passed through to the section header's reset affordance. */
+  sectionKey?: SectionKey
+  /** Nested under a fold already, see ThemeStudioSection. */
+  collapsible?: boolean
+}>(), {
+  // absent must stay undefined so the section's depth rule still decides
+  collapsible: undefined
+})
+
+const { rampChip } = useThemeStudio()
+const { shadeLadder, sections } = useTokenShades(props.alias)
+
+const title = computed(() => props.label ?? capitalize(props.alias))
+
+const paletteEditor = ref(false)
+const shadeEditor = ref(false)
+</script>
+
+<template>
+  <ThemeStudioSection :label="title" :help-to="helpTo" :section-key="sectionKey" :collapsible="collapsible">
+    <template #actions>
+      <ThemeStudioActionToggle
+        v-model="shadeEditor"
+        icon="i-lucide-settings-2"
+        tooltip="Adjust shades"
+        :aria-label="`Adjust ${alias} shades`"
+      />
+
+      <ThemeStudioActionToggle
+        v-model="paletteEditor"
+        icon="i-lucide-tangent"
+        tooltip="Edit palette"
+        :aria-label="`Edit ${alias} palette`"
+      />
+    </template>
+
+    <div>
+      <ThemeStudioColorMenu :alias="alias" />
+
+      <ThemeStudioPaletteEditor v-model:open="paletteEditor" :alias="alias" />
+
+      <!-- padding, not a margin: it has to sit inside the animated box -->
+      <UCollapsible v-model:open="shadeEditor" :ui="{ content: 'overflow-hidden' }">
+        <template #content>
+          <!-- the padding sits inside the animated box, not on it -->
+          <div class="pt-2">
+            <ThemeStudioShadeGroup
+              v-if="alias !== 'neutral'"
+              :label="`${title} shades`"
+              :sliders="sections[0]!.sliders"
+              :chip="rampChip(alias)"
+              :ladder="shadeLadder"
+            />
+
+            <!-- borders live in the Style panel's Borders section -->
+            <ThemeStudioTokenShades v-else :alias="alias" :groups="['background', 'text']" />
+          </div>
+        </template>
+      </UCollapsible>
+    </div>
+  </ThemeStudioSection>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioControls.vue b/docs/app/components/theme-studio/ThemeStudioControls.vue
new file mode 100644
index 0000000000..df6a75ec1e
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioControls.vue
@@ -0,0 +1,18 @@
+<script setup lang="ts">
+/** Which settings group this instance renders, one popover per group. */
+defineProps<{
+  group: 'colors' | 'style'
+}>()
+</script>
+
+<template>
+  <!-- One root either way: the panels render as fragments, so a class on the
+       component would fall through to nothing. Sections stay siblings here,
+       which is what lets each draw its own rule, the panel drops the leading
+       one, since there's nothing above it to separate from. -->
+  <div class="flex flex-col [&>*:first-child]:border-t-0">
+    <ThemeStudioControlsColors v-if="group === 'colors'" />
+
+    <ThemeStudioControlsDefaults v-else />
+  </div>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioControlsColors.vue b/docs/app/components/theme-studio/ThemeStudioControlsColors.vue
new file mode 100644
index 0000000000..948adb7d2f
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioControlsColors.vue
@@ -0,0 +1,34 @@
+<script setup lang="ts">
+import type { ColorAlias } from '../../utils/theme/engine'
+
+const semanticAliases: ColorAlias[] = ['secondary', 'success', 'info', 'warning', 'error']
+</script>
+
+<template>
+  <!-- Sections own their padding so the separators run edge to edge. -->
+  <ThemeStudioColorSection
+    alias="primary"
+    help-to="/docs/getting-started/theme/css-variables#colors"
+    section-key="primary"
+  />
+
+  <ThemeStudioColorSection
+    alias="neutral"
+    help-to="/docs/getting-started/theme/css-variables#text"
+    section-key="neutral"
+  />
+
+  <ThemeStudioSection
+    label="Semantic"
+    help-to="/docs/getting-started/theme/design-system"
+    :default-open="false"
+    section-key="semantic"
+  >
+    <ThemeStudioColorSection
+      v-for="alias in semanticAliases"
+      :key="alias"
+      :alias="alias"
+      :collapsible="false"
+    />
+  </ThemeStudioSection>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioControlsDefaults.vue b/docs/app/components/theme-studio/ThemeStudioControlsDefaults.vue
new file mode 100644
index 0000000000..9e423de1fe
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioControlsDefaults.vue
@@ -0,0 +1,187 @@
+<script setup lang="ts">
+import type { VariantGroup } from '../../utils/theme/engine'
+
+/**
+ * The variant and colour Buttons, Cards and Inputs start from. One fold over
+ * all three, collapsed and last, it's the least-reached-for control.
+ */
+const { style, setStyle } = useThemeStudio()
+
+// MD is the stock default, one deduped entry storing 'default'
+const defaultSizeItems = [
+  { label: 'XS', value: 'xs' },
+  { label: 'SM', value: 'sm' },
+  { label: 'MD', value: 'default', defaultTag: true },
+  { label: 'LG', value: 'lg' },
+  { label: 'XL', value: 'xl' }
+]
+
+const defaultSize = computed({
+  // legacy saved prefs may still pin 'md' explicitly, it IS the default
+  get: () => {
+    const size = style.value.defaults?.size || 'default'
+    return size === 'md' ? 'default' : size
+  },
+  set: (value: any) => setStyle({ defaults: { ...style.value.defaults, size: value } })
+})
+
+// Each group offers only what its components support; the app-wide
+// `variant` shows through as the fallback.
+const variantItems = (values: string[]) => values.map(value => ({ label: capitalize(value), value }))
+
+/** Variant names UButton can render itself, the rest (none) fall back. */
+const RENDERABLE_VARIANTS = ['solid', 'outline', 'soft', 'subtle', 'ghost', 'link']
+
+/** Variant grid popovers close on pick, one open flag per group. */
+const variantGridOpen = reactive<Record<string, boolean>>({ buttons: false, panels: false, inputs: false })
+
+// `stock` is the library's own default, picking it clears the override.
+const variantGroupFields = [
+  { key: 'buttons' as const, label: 'Button Defaults', hasColor: true, stock: 'solid', items: variantItems(['solid', 'outline', 'soft', 'subtle', 'ghost', 'link']) },
+  { key: 'panels' as const, label: 'Card Defaults', hasColor: false, stock: 'outline', items: variantItems(['solid', 'outline', 'soft', 'subtle']) },
+  { key: 'inputs' as const, label: 'Input Defaults', hasColor: true, stock: 'outline', items: variantItems(['outline', 'soft', 'subtle', 'ghost', 'none']) }
+]
+
+function groupVariantModel(group: VariantGroup) {
+  const supported = variantGroupFields.find(field => field.key === group)!.items.map(item => item.value)
+  return computed({
+    get: () => {
+      const own = style.value.defaults?.variants?.[group]
+      if (own && own !== 'default') return own
+      // An app-wide value this group can't express (e.g. solid inputs)
+      // truthfully reads as Default, the engine skips it there too.
+      const appWide = style.value.defaults?.variant
+      return appWide && supported.includes(appWide) ? appWide : 'default'
+    },
+    set: (value: any) => {
+      const defaults = style.value.defaults || {}
+
+      // Picking Default under an app-wide variant must actually win: the
+      // engine skips 'default' entries, so the app-wide value explodes
+      // into the OTHER groups (where they support it) and disappears.
+      if (value === 'default' && defaults.variant) {
+        const variants: Record<string, any> = {}
+        for (const field of variantGroupFields) {
+          if (field.key === group) continue
+          const existing = defaults.variants?.[field.key]
+          if (existing && existing !== 'default') {
+            variants[field.key] = existing
+          } else if (field.items.some(item => item.value === defaults.variant)) {
+            variants[field.key] = defaults.variant
+          }
+        }
+        const next = { ...defaults, variants }
+        delete next.variant
+        setStyle({ defaults: next })
+        return
+      }
+
+      setStyle({ defaults: { ...defaults, variants: { ...defaults.variants, [group]: value } } })
+    }
+  })
+}
+
+const groupVariants = Object.fromEntries(variantGroupFields.map(field => [field.key, groupVariantModel(field.key)])) as Record<VariantGroup, ReturnType<typeof groupVariantModel>>
+
+// Primary IS the stock default, one entry, tagged, storing 'default'
+// (an explicit 'primary' would export a no-op override).
+const defaultColorItems = [
+  { label: 'Primary', value: 'default', chip: { color: 'primary' as any }, defaultTag: true },
+  ...['secondary', 'success', 'info', 'warning', 'error', 'neutral'].map(value => ({
+    label: capitalize(value),
+    value,
+    chip: { color: value as any }
+  }))
+]
+
+function groupColorModel(group: VariantGroup) {
+  return computed({
+    get: () => style.value.defaults?.colors?.[group] || 'default',
+    set: (value: any) => setStyle({ defaults: { ...style.value.defaults, colors: { ...style.value.defaults?.colors, [group]: value } } })
+  })
+}
+
+const groupColors = Object.fromEntries(variantGroupFields.map(field => [field.key, groupColorModel(field.key)])) as Record<VariantGroup, ReturnType<typeof groupColorModel>>
+</script>
+
+<template>
+  <ThemeStudioSection
+    label="Default variants"
+    :default-open="false"
+    :section-key="[...variantGroupFields.map(field => field.key), 'size']"
+  >
+    <div class="pb-1.5">
+      <ThemeStudioRow
+        v-model="defaultSize"
+        control="select"
+        label="Size"
+        control-icon="i-lucide-proportions"
+        :items="defaultSizeItems"
+        aria-label="Default size"
+      />
+    </div>
+
+    <ThemeStudioSection
+      v-for="field in variantGroupFields"
+      :key="field.key"
+      :label="field.label"
+      :collapsible="false"
+    >
+      <div class="flex flex-col gap-1.5">
+        <ThemeStudioRow control="custom" label="Variant">
+          <UPopover v-model:open="variantGridOpen[field.key]" :content="{ side: 'bottom', align: 'start' }" class="flex-1">
+            <UButton
+              size="sm"
+              color="neutral"
+              variant="subtle"
+              block
+              icon="i-lucide-layers"
+              trailing-icon="i-lucide-chevron-down"
+              :ui="{ label: 'flex-1 text-left' }"
+              :aria-label="`${field.label} variant`"
+            >
+              <!-- the tag belongs in the grid, where it names the stock option -->
+              {{ field.items.find(item => item.value === (groupVariants[field.key].value === 'default' ? field.stock : groupVariants[field.key].value))?.label }}
+            </UButton>
+
+            <template #content>
+              <!-- each cell renders IN the variant it picks -->
+              <div class="w-64 p-2 grid grid-cols-2 gap-1">
+                <UButton
+                  v-for="item in field.items"
+                  :key="item.value"
+                  size="sm"
+                  block
+                  color="neutral"
+                  :variant="RENDERABLE_VARIANTS.includes(item.value) ? (item.value as any) : 'subtle'"
+                  :active="groupVariants[field.key].value === item.value || (groupVariants[field.key].value === 'default' && item.value === field.stock)"
+                  active-color="primary"
+                  :class="[item.value === 'none' && 'opacity-60', 'min-w-0']"
+                  @click="groupVariants[field.key].value = (item.value === field.stock ? 'default' : item.value); variantGridOpen[field.key] = false"
+                >
+                  <!-- opacity, not a color: text-dimmed would fight the variant's own text color -->
+                  <span class="truncate">{{ item.label }}<span v-if="item.value === field.stock" class="opacity-70 font-normal">&nbsp;(Default)</span></span>
+                </UButton>
+              </div>
+            </template>
+          </UPopover>
+        </ThemeStudioRow>
+
+        <ThemeStudioRow
+          v-if="field.hasColor"
+          v-model="groupColors[field.key].value"
+          control="select"
+          label="Color"
+          :items="defaultColorItems"
+          :aria-label="`${field.label} color`"
+        >
+          <template #leading>
+            <UChip
+              :color="((groupColors[field.key].value === 'default' ? 'primary' : groupColors[field.key].value) as any)"
+            />
+          </template>
+        </ThemeStudioRow>
+      </div>
+    </ThemeStudioSection>
+  </ThemeStudioSection>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioCurveEditor.vue b/docs/app/components/theme-studio/ThemeStudioCurveEditor.vue
new file mode 100644
index 0000000000..d382b5877c
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioCurveEditor.vue
@@ -0,0 +1,421 @@
+<script setup lang="ts">
+import { sampleCurve, SHADES, shadeX, parseColor, oklchToRgb } from '../../utils/theme/engine'
+import type { ChannelCurve } from '../../utils/theme/engine'
+
+const props = defineProps<{
+  /** Channel name, for the handles' accessible labels. */
+  label: string
+  /** Display window for the channel value axis */
+  yMin: number
+  yMax: number
+  /** Fill colors for the stop dots along the curve, one per stop. */
+  stopColors?: string[]
+  /** Curve x (0–1) per stop; omit for the standard 11 evenly-ranked stops. */
+  stopXs?: number[]
+  /** Which stops are pinned to an exact colour, aligned with `stopXs`. */
+  stopPinned?: boolean[]
+  /** Pin-corrected value per stop, so every dot sits on the colour it produces. */
+  stopValues?: number[]
+  /** Pin-corrected curve as a dense polyline, drawn in place of the raw bézier. */
+  actualCurve?: { x: number, v: number }[]
+  /** Colour field behind the plot: columns of oklch samples, top (yMax) to bottom. */
+  field?: string[][]
+}>()
+
+const curve = defineModel<ChannelCurve>({ required: true })
+
+const emit = defineEmits<{
+  dragStart: []
+  dragEnd: []
+}>()
+
+const W = 200
+const H = 180
+const PAD = 10
+
+function toX(x: number) {
+  return PAD + x * (W - 2 * PAD)
+}
+
+function toY(value: number) {
+  return PAD + (1 - (value - props.yMin) / (props.yMax - props.yMin)) * (H - 2 * PAD)
+}
+
+/** Handles stay grabbable even when a fitted param sits outside the window. */
+function toHandleY(value: number) {
+  return Math.min(H - PAD, Math.max(PAD, toY(value)))
+}
+
+function fromX(px: number) {
+  return Math.min(1, Math.max(0, (px - PAD) / (W - 2 * PAD)))
+}
+
+function fromY(py: number) {
+  return props.yMin + (1 - (py - PAD) / (H - 2 * PAD)) * (props.yMax - props.yMin)
+}
+
+const path = computed(() => {
+  // with pins the parent passes the corrected curve, draw it through the stops
+  if (props.actualCurve?.length) {
+    return props.actualCurve.map((p, i) => `${i ? 'L' : 'M'} ${toX(p.x).toFixed(2)} ${toY(p.v).toFixed(2)}`).join(' ')
+  }
+  const c = curve.value
+  return `M ${toX(0)} ${toY(c.y0)} C ${toX(c.p1x)} ${toY(c.p1y)}, ${toX(c.p2x)} ${toY(c.p2y)}, ${toX(1)} ${toY(c.y1)}`
+})
+
+// Paint the field as a small bitmap the canvas scales up with bilinear
+// smoothing, does what the SVG needed a blur filter for, without the filter
+// re-rasterising on every page restyle.
+const fieldCanvas = useTemplateRef<HTMLCanvasElement>('fieldCanvas')
+let sourceCanvas: HTMLCanvasElement | undefined
+
+function drawField() {
+  const canvas = fieldCanvas.value
+  const columns = props.field
+  if (!canvas || !columns?.length) return
+  const nCol = columns.length
+  const nRow = columns[0]!.length
+  if (!nRow) return
+
+  // low-res backing store stretched by CSS, indistinguishable for a soft gradient
+  if (canvas.width !== W * 3) {
+    canvas.width = W * 3
+    canvas.height = H * 3
+  }
+
+  const grid = new ImageData(nCol, nRow)
+  for (let col = 0; col < nCol; col++) {
+    const column = columns[col]!
+    for (let row = 0; row < nRow; row++) {
+      const parsed = parseColor(column[row]!)
+      const [r, g, b] = parsed ? oklchToRgb(parsed) : [0, 0, 0]
+      const i = (row * nCol + col) * 4
+      grid.data[i] = Math.round(r * 255)
+      grid.data[i + 1] = Math.round(g * 255)
+      grid.data[i + 2] = Math.round(b * 255)
+      grid.data[i + 3] = 255
+    }
+  }
+
+  if (!sourceCanvas) sourceCanvas = document.createElement('canvas')
+  sourceCanvas.width = nCol
+  sourceCanvas.height = nRow
+  sourceCanvas.getContext('2d')!.putImageData(grid, 0, 0)
+
+  const ctx = canvas.getContext('2d')!
+  ctx.imageSmoothingEnabled = true
+  ctx.imageSmoothingQuality = 'high'
+  ctx.clearRect(0, 0, canvas.width, canvas.height)
+  ctx.drawImage(sourceCanvas, 0, 0, nCol, nRow, 0, 0, canvas.width, canvas.height)
+}
+
+// Watch both explicitly, read-tracking would miss props.field behind the
+// early return while the canvas isn't mounted yet.
+watch([() => props.field, fieldCanvas], drawField, { immediate: true, flush: 'post' })
+
+// Endpoint handles ride the corrected line when a pin pulls the edge; a pinned
+// endpoint is locked from dragging, the pin owns it.
+const lastStop = computed(() => (props.stopValues?.length ?? 1) - 1)
+const startPinned = computed(() => props.stopPinned?.[0] ?? false)
+const endPinned = computed(() => props.stopPinned?.[lastStop.value] ?? false)
+const startY = computed(() => props.stopValues?.[0] ?? curve.value.y0)
+const endY = computed(() => props.stopValues?.[lastStop.value] ?? curve.value.y1)
+
+const stopXs = computed(() => props.stopXs ?? SHADES.map(shadeX))
+const stops = computed(() => stopXs.value.map((x, index) => {
+  // dots ride the drawn (pin-corrected) line; bézier sample when no pins
+  const value = props.stopValues?.[index] ?? sampleCurve(x, curve.value)
+  return {
+    key: index,
+    cx: toX(x),
+    cy: toY(value),
+    fill: props.stopColors?.[index] || 'currentColor',
+    pinned: props.stopPinned?.[index] ?? false
+  }
+}))
+
+// Dots track the stop spacing, or a dense ramp draws them as one fat band.
+const stopRadius = computed(() => Math.min(2.25, Math.max(0.9, (W - 2 * PAD) / (stops.value.length * 2.4))))
+
+const svgRef = ref<SVGSVGElement>()
+const dragging = ref<'y0' | 'y1' | 'p1' | 'p2' | null>(null)
+
+function svgPoint(event: PointerEvent): { x: number, y: number } {
+  const rect = svgRef.value!.getBoundingClientRect()
+  return {
+    x: (event.clientX - rect.left) * (W / rect.width),
+    y: (event.clientY - rect.top) * (H / rect.height)
+  }
+}
+
+function onPointerDown(event: PointerEvent) {
+  // right/middle clicks must not start a drag (the context menu would
+  // strand the page-wide dragging state)
+  if (event.button !== 0) return
+  const point = svgPoint(event)
+  const c = curve.value
+
+  const targets = [
+    { id: 'p1' as const, x: toX(c.p1x), y: toHandleY(c.p1y) },
+    { id: 'p2' as const, x: toX(c.p2x), y: toHandleY(c.p2y) },
+    // a pinned endpoint is locked
+    ...(startPinned.value ? [] : [{ id: 'y0' as const, x: toX(0), y: toHandleY(startY.value) }]),
+    ...(endPinned.value ? [] : [{ id: 'y1' as const, x: toX(1), y: toHandleY(endY.value) }])
+  ]
+
+  let best: { id: typeof dragging.value, distance: number } = { id: null, distance: 14 }
+  for (const target of targets) {
+    const distance = Math.hypot(target.x - point.x, target.y - point.y)
+    if (distance < best.distance) {
+      best = { id: target.id, distance }
+    }
+  }
+
+  if (best.id) {
+    dragging.value = best.id
+    svgRef.value!.setPointerCapture(event.pointerId)
+    event.preventDefault()
+    emit('dragStart')
+  }
+}
+
+function onPointerMove(event: PointerEvent) {
+  if (!dragging.value) return
+
+  const point = svgPoint(event)
+  const value = fromY(point.y)
+  // window-clamped: an overshot handle would leave the canvas and become
+  // ungrabbable (and out-of-range lightness exports nonsense)
+  const clamped = Math.min(props.yMax, Math.max(props.yMin, value))
+
+  // An endpoint drag carries its control handle by the same delta (tangent
+  // preserved). The handle sits on the corrected curve but steers the raw
+  // control, back out the pin pull (corrected − raw) to track the pointer.
+  if (dragging.value === 'y0') {
+    const raw = Math.min(props.yMax, Math.max(props.yMin, clamped - (startY.value - curve.value.y0)))
+    const delta = raw - curve.value.y0
+    const p1y = Math.min(props.yMax, Math.max(props.yMin, curve.value.p1y + delta))
+    curve.value = { ...curve.value, y0: raw, p1y }
+  } else if (dragging.value === 'y1') {
+    const raw = Math.min(props.yMax, Math.max(props.yMin, clamped - (endY.value - curve.value.y1)))
+    const delta = raw - curve.value.y1
+    const p2y = Math.min(props.yMax, Math.max(props.yMin, curve.value.p2y + delta))
+    curve.value = { ...curve.value, y1: raw, p2y }
+  } else if (dragging.value === 'p1') {
+    curve.value = { ...curve.value, p1x: fromX(point.x), p1y: clamped }
+  } else {
+    curve.value = { ...curve.value, p2x: fromX(point.x), p2y: clamped }
+  }
+}
+
+function onPointerUp(event: PointerEvent) {
+  if (dragging.value) {
+    dragging.value = null
+    // after a pointercancel the capture is gone and release throws, which
+    // would skip dragEnd and strand the page-wide dragging class
+    if (svgRef.value?.hasPointerCapture(event.pointerId)) {
+      svgRef.value.releasePointerCapture(event.pointerId)
+    }
+    emit('dragEnd')
+  }
+}
+
+type Handle = 'y0' | 'p1' | 'p2' | 'y1'
+
+const keyEditing = ref(false)
+let keyEndTimeout: ReturnType<typeof setTimeout> | undefined
+
+// A run of keypresses is one edit: dragEnd settles after a pause so the
+// parent commits once, as it does for a pointer drag.
+function beginKeyEdit() {
+  if (!keyEditing.value) {
+    keyEditing.value = true
+    emit('dragStart')
+  }
+  clearTimeout(keyEndTimeout)
+  keyEndTimeout = setTimeout(() => {
+    keyEditing.value = false
+    emit('dragEnd')
+  }, 300)
+}
+
+function nudge(handle: Handle, axis: 'x' | 'y', direction: number, coarse: boolean) {
+  const c = curve.value
+  if (axis === 'y') {
+    const step = (props.yMax - props.yMin) / (coarse ? 10 : 100) * direction
+    const clamp = (value: number) => Math.min(props.yMax, Math.max(props.yMin, value))
+    // endpoints carry their control handle, matching the pointer drag
+    if (handle === 'y0') curve.value = { ...c, y0: clamp(c.y0 + step), p1y: clamp(c.p1y + step) }
+    else if (handle === 'y1') curve.value = { ...c, y1: clamp(c.y1 + step), p2y: clamp(c.p2y + step) }
+    else if (handle === 'p1') curve.value = { ...c, p1y: clamp(c.p1y + step) }
+    else curve.value = { ...c, p2y: clamp(c.p2y + step) }
+    return
+  }
+  const step = (coarse ? 0.1 : 0.01) * direction
+  const clamp = (value: number) => Math.min(1, Math.max(0, value))
+  if (handle === 'p1') curve.value = { ...c, p1x: clamp(c.p1x + step) }
+  else if (handle === 'p2') curve.value = { ...c, p2x: clamp(c.p2x + step) }
+}
+
+function jump(handle: Handle, to: 'min' | 'max') {
+  const c = curve.value
+  const value = to === 'min' ? props.yMin : props.yMax
+  if (handle === 'y0') curve.value = { ...c, y0: value }
+  else if (handle === 'y1') curve.value = { ...c, y1: value }
+  else if (handle === 'p1') curve.value = { ...c, p1y: value }
+  else curve.value = { ...c, p2y: value }
+}
+
+function onKeydown(handle: Handle, event: KeyboardEvent) {
+  // a pin owns its endpoint, same lock the pointer path applies
+  if ((handle === 'y0' && startPinned.value) || (handle === 'y1' && endPinned.value)) return
+
+  const steps: Record<string, () => void> = {
+    ArrowUp: () => nudge(handle, 'y', 1, event.shiftKey),
+    ArrowDown: () => nudge(handle, 'y', -1, event.shiftKey),
+    ArrowRight: () => nudge(handle, 'x', 1, event.shiftKey),
+    ArrowLeft: () => nudge(handle, 'x', -1, event.shiftKey),
+    Home: () => jump(handle, 'min'),
+    End: () => jump(handle, 'max')
+  }
+  const step = steps[event.key]
+  if (!step) return
+
+  step()
+  event.preventDefault()
+  beginKeyEdit()
+}
+
+/** Rounded for `aria-valuenow`, hue reads in degrees, the rest need decimals. */
+function readout(value: number) {
+  return props.yMax - props.yMin > 10 ? Math.round(value) : Number(value.toFixed(3))
+}
+
+const handles = computed(() => [
+  { id: 'y0' as const, label: `${props.label} start`, cx: toX(0), cy: toHandleY(startY.value), value: startY.value, locked: startPinned.value },
+  { id: 'p1' as const, label: `${props.label} control point 1`, cx: toX(curve.value.p1x), cy: toHandleY(curve.value.p1y), value: curve.value.p1y, locked: false },
+  { id: 'p2' as const, label: `${props.label} control point 2`, cx: toX(curve.value.p2x), cy: toHandleY(curve.value.p2y), value: curve.value.p2y, locked: false },
+  { id: 'y1' as const, label: `${props.label} end`, cx: toX(1), cy: toHandleY(endY.value), value: endY.value, locked: endPinned.value }
+])
+
+// Closing the fold mid-drag unmounts the SVG without a pointerup, emit dragEnd
+// so the parent isn't left with isDragging and stranded preview vars.
+onUnmounted(() => {
+  clearTimeout(keyEndTimeout)
+  if (dragging.value || keyEditing.value) {
+    dragging.value = null
+    keyEditing.value = false
+    emit('dragEnd')
+  }
+})
+</script>
+
+<template>
+  <div class="relative w-full rounded-t-sm ring ring-default bg-elevated/30 overflow-hidden">
+    <!-- canvas, not SVG gradients + blur: the filter re-rasterised on every
+         page restyle (~7ms per apply during a drag) -->
+    <canvas
+      ref="fieldCanvas"
+      class="absolute inset-0 size-full opacity-75 pointer-events-none"
+    />
+    <svg
+      ref="svgRef"
+      data-curve-editor
+      :viewBox="`0 0 ${W} ${H}`"
+      class="relative block w-full touch-none select-none cursor-crosshair"
+      @pointerdown="onPointerDown"
+      @pointermove="onPointerMove"
+      @pointerup="onPointerUp"
+      @pointercancel="onPointerUp"
+    >
+      <!-- handle connectors -->
+      <line
+        :x1="toX(0)"
+        :y1="toHandleY(startY)"
+        :x2="toX(curve.p1x)"
+        :y2="toHandleY(curve.p1y)"
+        class="stroke-(--ui-text-dimmed)"
+        stroke-width="0.75"
+        stroke-dasharray="2 2"
+      />
+      <line
+        :x1="toX(1)"
+        :y1="toHandleY(endY)"
+        :x2="toX(curve.p2x)"
+        :y2="toHandleY(curve.p2y)"
+        class="stroke-(--ui-text-dimmed)"
+        stroke-width="0.75"
+        stroke-dasharray="2 2"
+      />
+
+      <!-- curve -->
+      <path :d="path" fill="none" class="stroke-(--ui-primary)" stroke-width="1.5" />
+
+      <!-- shade stops on the curve; a pinned stop wears a larger primary ring -->
+      <template v-for="stop in stops" :key="stop.key">
+        <circle
+          v-if="stop.pinned"
+          :cx="stop.cx"
+          :cy="stop.cy"
+          :r="stopRadius + 1.75"
+          fill="none"
+          class="stroke-(--ui-primary)"
+          stroke-width="1.25"
+        />
+        <circle
+          :cx="stop.cx"
+          :cy="stop.cy"
+          :r="stop.pinned ? stopRadius + 0.25 : stopRadius"
+          :fill="stop.fill"
+          class="stroke-(--ui-bg)"
+          stroke-width="0.5"
+        />
+      </template>
+
+      <!-- handles -->
+      <circle :cx="toX(curve.p1x)" :cy="toHandleY(curve.p1y)" r="4" class="fill-(--ui-bg) stroke-(--ui-text-muted)" stroke-width="1.25" />
+      <circle :cx="toX(curve.p2x)" :cy="toHandleY(curve.p2y)" r="4" class="fill-(--ui-bg) stroke-(--ui-text-muted)" stroke-width="1.25" />
+
+      <!-- endpoints, filled with the ramp's 50 and 950 so the drag targets show
+         what they steer -->
+      <circle
+        :cx="toX(0)"
+        :cy="toHandleY(startY)"
+        r="4.5"
+        :fill="stopColors?.[0] || 'currentColor'"
+        class="stroke-(--ui-text-highlighted)"
+        stroke-width="1.5"
+      />
+      <circle
+        :cx="toX(1)"
+        :cy="toHandleY(endY)"
+        r="4.5"
+        :fill="stopColors?.[stopColors.length - 1] || 'currentColor'"
+        class="stroke-(--ui-text-highlighted)"
+        stroke-width="1.5"
+      />
+
+      <!-- Focus layer over the decorative handles. Transparent fill still
+           hit-tests (`none` would not), so drags keep bubbling to the svg. -->
+      <circle
+        v-for="handle in handles"
+        :key="handle.id"
+        :cx="handle.cx"
+        :cy="handle.cy"
+        r="6"
+        fill="transparent"
+        stroke="transparent"
+        stroke-width="1.5"
+        :tabindex="handle.locked ? -1 : 0"
+        role="slider"
+        :aria-label="handle.label"
+        :aria-valuemin="yMin"
+        :aria-valuemax="yMax"
+        :aria-valuenow="readout(handle.value)"
+        :aria-disabled="handle.locked || undefined"
+        class="cursor-grab focus:outline-none focus-visible:stroke-(--ui-primary)"
+        @keydown="onKeydown(handle.id, $event)"
+      />
+    </svg>
+  </div>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioDefaultSelect.vue b/docs/app/components/theme-studio/ThemeStudioDefaultSelect.vue
new file mode 100644
index 0000000000..72d3c32cbd
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioDefaultSelect.vue
@@ -0,0 +1,55 @@
+<script setup lang="ts">
+import type { ChipProps } from '@nuxt/ui'
+
+/**
+ * A USelect whose stock choice is deduped into a single tagged entry, the
+ * item carrying `defaultTag` renders a muted "(Default)" suffix in the LIST,
+ * where it tells you which option is the stock one. The trigger shows the
+ * plain label: there it only lengthens the value you already picked.
+ */
+export interface DefaultSelectItem {
+  label: string
+  value: string
+  defaultTag?: boolean
+  chip?: ChipProps
+}
+
+const props = defineProps<{
+  items: DefaultSelectItem[]
+  icon?: string
+  ariaLabel?: string
+}>()
+
+const model = defineModel<string>({ required: true })
+
+const selected = computed(() => props.items.find(item => item.value === model.value))
+
+/** The slot scope types items as the broad SelectItem union, narrow it. */
+function asItem(item: unknown) {
+  return item as DefaultSelectItem
+}
+</script>
+
+<template>
+  <USelect
+    v-model="model"
+    size="sm"
+    color="neutral"
+    variant="subtle"
+    :icon="icon"
+    :items="items"
+    :aria-label="ariaLabel"
+  >
+    <template v-if="$slots.leading" #leading>
+      <slot name="leading" />
+    </template>
+
+    <template #default>
+      {{ selected?.label }}
+    </template>
+
+    <template #item-label="{ item }">
+      {{ asItem(item).label }}<span v-if="asItem(item).defaultTag" class="text-dimmed">&nbsp;(Default)</span>
+    </template>
+  </USelect>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioFontOptions.vue b/docs/app/components/theme-studio/ThemeStudioFontOptions.vue
new file mode 100644
index 0000000000..6b262a94ab
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioFontOptions.vue
@@ -0,0 +1,134 @@
+<script setup lang="ts">
+import { FONT_WEIGHT_DEFAULTS, loadFontPreviews } from '../../utils/theme/studio'
+
+/**
+ * Every typographic setting in one panel: the three stacks up top, then the
+ * treatment that rides on them. They were split across the toolbar and the
+ * Options panel before, which meant the type decisions were never on screen
+ * together.
+ *
+ * The stacks are what tailwind reads. Mono needs nothing else (preflight
+ * points `code`/`kbd`/`pre`/`samp` at it) and serif drives the h1–h6 rule in
+ * main.css until v5 ships `--ui-font-heading`.
+ */
+const { fonts, font, fontPrefs, setFontPrefs, fontSize } = useTheme()
+
+onMounted(() => loadFontPreviews(fonts.map(entry => entry.name)))
+
+// One writable model per tailwind weight step, the knobs components
+// actually dereference at runtime.
+function weightStepModel(step: keyof typeof FONT_WEIGHT_DEFAULTS) {
+  return computed({
+    get: () => fontPrefs.value.weights?.[step] ?? FONT_WEIGHT_DEFAULTS[step],
+    set: (value: number) => setFontPrefs({ ...fontPrefs.value, weights: { ...fontPrefs.value.weights, [step]: value } })
+  })
+}
+
+const WEIGHT_STEPS = ['normal', 'medium', 'semibold', 'bold'] as const
+const weightSteps = Object.fromEntries(WEIGHT_STEPS.map(step => [step, weightStepModel(step)])) as Record<typeof WEIGHT_STEPS[number], ReturnType<typeof weightStepModel>>
+const weights = WEIGHT_STEPS.map(step => ({ label: capitalize(step), model: weightSteps[step]! }))
+
+const uppercase = computed({
+  get: () => !!fontPrefs.value.uppercase,
+  set: (value: boolean) => setFontPrefs({ ...fontPrefs.value, uppercase: value })
+})
+
+const letterSpacing = computed({
+  get: () => fontPrefs.value.letterSpacing ?? 0,
+  set: (value: number) => setFontPrefs({ ...fontPrefs.value, letterSpacing: value })
+})
+
+const lineHeight = computed({
+  get: () => fontPrefs.value.lineHeight ?? 1.5,
+  set: (value: number) => setFontPrefs({ ...fontPrefs.value, lineHeight: value })
+})
+
+/**
+ * Tailwind's other two stacks, labelled by what they drive rather than by
+ * their variable. `undefined` (not the string) is inherit, so an untouched
+ * row exports clean; the body stack always resolves, so it has no inherit.
+ */
+function stackModel(key: 'serif' | 'mono') {
+  return computed({
+    get: () => fontPrefs.value[key] ?? 'inherit',
+    set: (value: string) => setFontPrefs({ ...fontPrefs.value, [key]: value === 'inherit' ? undefined : value })
+  })
+}
+
+const stacks = [
+  { label: 'Body', model: font, inherit: false, default: 'Public Sans', hint: 'Body font' },
+  { label: 'Heading', model: stackModel('serif'), inherit: true, default: undefined, hint: 'Heading font' },
+  { label: 'Code', model: stackModel('mono'), inherit: true, default: undefined, hint: 'Code font' }
+]
+</script>
+
+<template>
+  <div class="w-72 p-3 flex flex-col gap-1.5">
+    <ThemeStudioRow
+      v-for="stack in stacks"
+      :key="stack.label"
+      control="custom"
+      :label="stack.label"
+    >
+      <ThemeStudioFontPicker
+        v-model="stack.model.value"
+        :curated="fonts"
+        :default-value="stack.default"
+        :inherit="stack.inherit"
+        :aria-label="stack.hint"
+      />
+    </ThemeStudioRow>
+
+    <USeparator class="my-1" />
+
+    <!-- font-size scales every rem metric, so it belongs with the type
+         decisions rather than beside radius -->
+    <ThemeStudioRow
+      v-model="fontSize"
+      control="slider"
+      label="Size"
+      :min="14"
+      :max="18"
+      :step="0.5"
+      unit="px"
+    />
+
+    <ThemeStudioRow
+      v-model="letterSpacing"
+      control="slider"
+      label="Spacing"
+      :min="-0.05"
+      :max="0.25"
+      :step="0.005"
+      unit="em"
+    />
+
+    <ThemeStudioRow
+      v-model="lineHeight"
+      control="slider"
+      label="Height"
+      :min="1"
+      :max="2"
+      :step="0.05"
+    />
+
+    <ThemeStudioRow
+      v-model="uppercase"
+      control="switch"
+      label="Uppercase"
+    />
+
+    <USeparator class="my-1" />
+
+    <ThemeStudioRow
+      v-for="weight in weights"
+      :key="weight.label"
+      v-model="weight.model.value"
+      control="slider"
+      :label="weight.label"
+      :min="100"
+      :max="900"
+      :step="25"
+    />
+  </div>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioFontPicker.vue b/docs/app/components/theme-studio/ThemeStudioFontPicker.vue
new file mode 100644
index 0000000000..7eb9dc5d95
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioFontPicker.vue
@@ -0,0 +1,133 @@
+<script setup lang="ts">
+/**
+ * A font family picker: the curated shortlist grouped by category up front,
+ * with a search box over the full Google Fonts catalog (fetched lazily on
+ * first open). Rows render themselves in their own face, and each result
+ * batch loads its preview faces, debounced so keystrokes don't fan out into
+ * stylesheet requests.
+ *
+ * Every instance offers all three categories. The stacks are independent, so
+ * the slot a picker fills says nothing about which face belongs in it.
+ */
+import { watchDebounced } from '@vueuse/core'
+import { loadFontPreviews, keepPanels } from '../../utils/theme/studio'
+import type { FontCategory } from '../../composables/useTheme'
+
+const props = defineProps<{
+  /** The shortlist offered before the user searches. */
+  curated: Array<{ name: string, category: FontCategory }>
+  /** The value that wears the (Default) tag. */
+  defaultValue?: string
+  /** Prepend an "Inherit" option, for the stacks that may follow the body. */
+  inherit?: boolean
+  ariaLabel?: string
+}>()
+
+const model = defineModel<string>({ required: true })
+
+const { status, load, search } = useGoogleFonts()
+// the studio chrome skins to the applied pack, the search glyph included
+const appConfig = useAppConfig()
+
+const open = ref(false)
+const query = ref('')
+
+// A stale query would flash old results on reopen; the catalog fetch only
+// starts once someone actually reaches for the picker.
+watch(open, (value) => {
+  if (value) {
+    query.value = ''
+    load()
+  }
+})
+
+const results = computed(() => open.value ? search(query.value) : [])
+
+/** Google reports `sans-serif` / `monospace` / `display` / `handwriting`. */
+function categoryOf(raw: string): FontCategory {
+  if (raw.startsWith('mono')) return 'Mono'
+  if (raw === 'serif') return 'Serif'
+  return 'Sans'
+}
+
+type FontItem = { label: string, value?: string, type?: 'label' }
+
+/** One group per category, each led by its own label row. */
+function group(entries: Array<{ name: string, category: FontCategory }>): FontItem[][] {
+  return (['Sans', 'Serif', 'Mono'] as const)
+    .map(category => ({ category, entries: entries.filter(entry => entry.category === category) }))
+    .filter(({ entries }) => entries.length)
+    .map(({ category, entries }) => [
+      { label: category, type: 'label' as const },
+      ...entries.map(entry => ({ label: entry.name, value: entry.name }))
+    ])
+}
+
+const items = computed<FontItem[][]>(() => {
+  if (query.value.trim()) {
+    return group(results.value.map(font => ({ name: font.name, category: categoryOf(font.category) })))
+  }
+  const curated = [...props.curated]
+  // A searched pick isn't in the shortlist, pin it on top so the selection
+  // stays visible (and deselectable) on reopen.
+  if (model.value !== 'inherit' && !curated.some(entry => entry.name === model.value)) {
+    curated.unshift({ name: model.value, category: 'Sans' })
+  }
+  return [
+    ...(props.inherit ? [[{ label: 'Inherit', value: 'inherit' }]] : []),
+    ...group(curated)
+  ]
+})
+
+watchDebounced(results, value => loadFontPreviews(value.map(font => font.name)), { debounce: 250 })
+
+const empty = computed(() => {
+  if (status.value === 'loading') return 'Loading the Google Fonts catalog…'
+  if (status.value === 'error') return 'Couldn’t load the Google Fonts catalog'
+  return 'No fonts match your search'
+})
+
+/** Rows preview themselves; `inherit` has no face of its own to show. */
+function faceOf(value?: string) {
+  return !value || value === 'inherit' ? undefined : { fontFamily: `'${value}', sans-serif` }
+}
+</script>
+
+<template>
+  <USelectMenu
+    v-model="model"
+    v-model:open="open"
+    v-model:search-term="query"
+    :items="items"
+    value-key="value"
+    ignore-filter
+    :content="{ onInteractOutside: keepPanels, sideOffset: 7 }"
+    :search-input="{ placeholder: 'Search Google Fonts…', icon: appConfig.ui.icons.search }"
+    :aria-label="ariaLabel"
+    size="sm"
+    class="w-full"
+    :ui="{ content: 'w-(--reka-combobox-trigger-width)', trailingIcon: 'transition-transform duration-200 group-data-[state=open]:rotate-180' }"
+  >
+    <!-- No inline face on the trigger: the panel already renders in the body
+         font, so the name inherits it. -->
+    <template #default>
+      <span class="truncate">{{ model === 'inherit' ? 'Inherit' : model }}</span>
+    </template>
+
+    <template #item-label="{ item }">
+      <span :style="faceOf(item.value)">{{ item.label }}</span><span v-if="item.value && item.value === defaultValue" class="text-dimmed">&nbsp;(Default)</span>
+    </template>
+
+    <template #item-description="{ item }">
+      <span
+        v-if="item.value && item.value !== 'inherit'"
+        class="text-xs text-muted truncate"
+        :style="faceOf(item.value)"
+      >Grumpy wizards make toxic brew</span>
+    </template>
+
+    <template #empty>
+      {{ empty }}
+    </template>
+  </USelectMenu>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioIconOptions.vue b/docs/app/components/theme-studio/ThemeStudioIconOptions.vue
new file mode 100644
index 0000000000..5456814ac8
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioIconOptions.vue
@@ -0,0 +1,53 @@
+<script setup lang="ts">
+import { iconSetSamples } from '../../utils/theme/icons'
+import { keepPanels } from '../../utils/theme/studio'
+
+/** The icon set picker: the toolbar control itself, not a panel. */
+defineProps<{ tooltip?: string, dirty?: boolean }>()
+
+// The tooltip has to wrap the trigger, so it takes the root; forward the
+// caller's class past it or the toolbar's width lands on nothing.
+defineOptions({ inheritAttrs: false })
+
+/** Exposed so the toolbar can pin itself while the list is open. */
+const open = defineModel<boolean>('open', { default: false })
+
+const { icon, icons } = useTheme()
+</script>
+
+<template>
+  <UTooltip :text="tooltip" :disabled="!tooltip">
+    <USelectMenu
+      v-model="icon"
+      v-model:open="open"
+      :items="icons"
+      value-key="value"
+      :icon="icons.find(entry => entry.value === icon)?.icon"
+      :content="{ onInteractOutside: keepPanels }"
+      :search-input="false"
+      :color="dirty ? 'primary' : 'neutral'"
+      :highlight="dirty"
+      variant="outline"
+      aria-label="Icon set"
+      :ui="{
+        base: dirty && 'ring-primary/50 text-primary',
+        leadingIcon: dirty && 'text-primary',
+        trailingIcon: dirty && 'text-primary',
+        content: 'w-72'
+      }"
+      v-bind="$attrs"
+    >
+      <!-- every set previews a strip of its own glyphs -->
+      <template #item-description="{ item }">
+        <span class="flex items-center gap-1.5 pt-0.5">
+          <UIcon
+            v-for="name in iconSetSamples(item.value)"
+            :key="name"
+            :name="name"
+            class="size-3.5 text-muted"
+          />
+        </span>
+      </template>
+    </USelectMenu>
+  </UTooltip>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioPaletteEditor.vue b/docs/app/components/theme-studio/ThemeStudioPaletteEditor.vue
new file mode 100644
index 0000000000..33fb5be1e7
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioPaletteEditor.vue
@@ -0,0 +1,727 @@
+<script setup lang="ts">
+import { useThrottleFn, watchIgnorable } from '@vueuse/core'
+import { SHADES_ALL, SHADE_STEPS, SHADE_SETS, CURVE_DEFAULTS, NEUTRAL_CURVE_DEFAULTS, PALETTE_EFFECT_DEFAULTS, generatePalette, buildRampSampler, fitPalette, applyPaletteEffects, isDefaultEffects, sampleCurve, shadeX, storedStopStep, detectStopStep, clampToGamut, formatOklch, parseColor, oklchToRgb, rgbToHex } from '../../utils/theme/engine'
+import type { PaletteCurveParams, PaletteEffects, StoredPaletteParams, PalettePin, Shade, ShadeStep, ColorAlias } from '../../utils/theme/engine'
+
+const props = defineProps<{
+  alias: ColorAlias
+}>()
+
+const appConfig = useAppConfig()
+const { paletteParams, isCustomPalette, paletteShades, setPaletteFromCurve } = useThemeStudio()
+
+const open = defineModel<boolean>('open', { default: false })
+const tab = ref<'lightness' | 'chroma' | 'hue'>('lightness')
+
+const tabs = [
+  { label: 'Lightness', value: 'lightness' as const },
+  { label: 'Chroma', value: 'chroma' as const },
+  { label: 'Hue', value: 'hue' as const }
+]
+
+function defaults(): PaletteCurveParams {
+  return structuredClone(props.alias === 'neutral' ? NEUTRAL_CURVE_DEFAULTS : CURVE_DEFAULTS)
+}
+
+/** The stored entry's base curves, without the lens. */
+function pickCurves(value: StoredPaletteParams): PaletteCurveParams {
+  return structuredClone({ lightness: toRaw(value.lightness), chroma: toRaw(value.chroma), hue: toRaw(value.hue) })
+}
+
+// Elements read off the reactive ref are Vue Proxies toRaw doesn't unwrap,
+// structuredClone would throw. Rebuild from scalars.
+function plainPins(pins: readonly PalettePin[]): PalettePin[] {
+  return pins.map(pin => ({ shade: pin.shade, l: pin.l, c: pin.c, h: pin.h }))
+}
+
+// Restore the lens too, so a reload doesn't silently bake the sliders in.
+const stored = paletteParams.value[props.alias]
+const effects = reactive<PaletteEffects>({ ...PALETTE_EFFECT_DEFAULTS, ...(stored?.effects ?? {}) })
+const effectAmount = ref(stored?.amount ?? 100)
+
+// Stop density: 100 = the standard 11 stops; finer steps subdivide to 19/37/91.
+const stopStep = ref<ShadeStep>(storedStopStep(stored))
+const stopSet = computed(() => SHADE_SETS[stopStep.value])
+
+const stopItems = SHADE_STEPS.map(step => ({ label: `${step}`, value: step }))
+
+// Stops locked to an exact colour, the curves bend to pass through them.
+// Kept a plain cloneable array (persisted, fed to generatePalette).
+const pins = ref<PalettePin[]>(stored?.pins ? plainPins(stored.pins) : [])
+// shade → pin lightness: `has` answers "pinned?", the badge reads L for contrast
+const pinnedShades = computed(() => new Map(pins.value.map(pin => [pin.shade, pin.l])))
+
+// L above which a stop takes the dark badge. Whole class strings, tailwind's
+// scanner only sees literals.
+const LIGHT_STOP_L = 0.62
+const PIN_BADGE_CLASS = {
+  text: { onLight: 'text-(--ui-color-neutral-950)', onDark: 'text-(--ui-color-neutral-50)' },
+  bg: { onLight: 'bg-(--ui-color-neutral-950)', onDark: 'bg-(--ui-color-neutral-50)' }
+} as const
+
+// The neutral end that contrasts with the stop, a `difference` blend vanishes
+// at mid lightness and inverts saturated hues.
+function pinBadgeClass(shade: number, property: 'text' | 'bg') {
+  const lightness = pinnedShades.value.get(shade as Shade) ?? 0
+  return PIN_BADGE_CLASS[property][lightness > LIGHT_STOP_L ? 'onLight' : 'onDark']
+}
+
+function setPin(shade: number, oklch: string) {
+  const parsed = parseColor(oklch)
+  if (!parsed) return false
+  const next = pins.value.filter(pin => pin.shade !== shade)
+  next.push({ shade: shade as Shade, l: parsed.l, c: parsed.c, h: parsed.h })
+  pins.value = next
+  return true
+}
+
+function removePin(shade: number) {
+  pins.value = pins.value.filter(pin => pin.shade !== shade)
+}
+
+/** Toggle a lock; pinning grabs whatever colour the stop currently shows. */
+function togglePinExact(shade: number) {
+  if (pinnedShades.value.has(shade as Shade)) removePin(shade)
+  else setPin(shade, shades.value[shade as Shade] ?? '')
+}
+
+/** Base curves the modifiers transform from, so they never compound. */
+let seedBase: PaletteCurveParams
+  = stored && 'lightness' in stored ? pickCurves(stored) : defaults()
+// Stored params may predate the fixed 0–360 axis (or carry unwrapped hues).
+normalizeHue(seedBase)
+
+/** The DISPLAYED curves: base with the lens applied, what generates the ramp. */
+const params = reactive<PaletteCurveParams>(applyPaletteEffects(seedBase, effects, effectAmount.value))
+
+const active = computed(() => isCustomPalette(props.alias))
+
+const shades = computed(() => generatePalette(params, stopStep.value, pins.value))
+const stopColors = computed(() => stopSet.value.map(shade => shades.value[shade]))
+const stopXs = computed(() => stopSet.value.map(shadeX))
+const stopPinned = computed(() => stopSet.value.map(shade => pinnedShades.value.has(shade)))
+// Pin-corrected values: the editor draws the polyline so the line bends THROUGH
+// pinned stops. Sampler built on the reactive params so a handle drag redraws.
+const CHANNEL_KEY = { lightness: 'l', chroma: 'c', hue: 'h' } as const
+const stopValues = computed(() => {
+  const key = CHANNEL_KEY[tab.value]
+  const sample = buildRampSampler(params, pins.value)
+  return stopSet.value.map(shade => sample(shadeX(shade))[key])
+})
+const actualCurve = computed(() => {
+  // no pins → no correction, draw the exact bézier
+  if (!pins.value.length) return undefined
+  const key = CHANNEL_KEY[tab.value]
+  const sample = buildRampSampler(params, pins.value)
+  return Array.from({ length: 48 }, (_, i) => {
+    const x = i / 47
+    return { x, v: sample(x)[key] }
+  })
+})
+
+// Kept light (no hex/rgb parse), recomputes every drag frame across up to 91
+// stops; the parse is deferred to the single open swatch.
+const swatches = computed(() => stopSet.value.map(shade => ({ shade, oklch: shades.value[shade]! })))
+
+const { copy: copyShade } = useClipboard()
+const copiedShade = ref<number>()
+let copiedTimeout: ReturnType<typeof setTimeout> | undefined
+
+function copySwatch(info: { shade: number, oklch: string }) {
+  copyShade(info.oklch)
+  copiedShade.value = info.shade
+  clearTimeout(copiedTimeout)
+  copiedTimeout = setTimeout(() => {
+    copiedShade.value = undefined
+  }, 1500)
+}
+onUnmounted(() => clearTimeout(copiedTimeout))
+
+// A popover, not a tooltip: the copy button and inputs must take focus. Hover
+// previews it (with a grace gap); click STICKS it open for typing. Stick ≠ pin:
+// a stick keeps the popover visible, a pin locks the stop's colour.
+const stuckShade = ref<number>()
+const hoveredShade = ref<number>()
+let hoverLeaveTimeout: ReturnType<typeof setTimeout> | undefined
+
+// One popover serves the whole strip (stuck wins over hover), a single Reka
+// instance instead of one per stop is the bulk of the 19-stop speedup.
+const activeShade = computed(() => stuckShade.value ?? hoveredShade.value)
+
+// Full detail for the ONE open swatch, the oklch→rgb→hex parse runs here only.
+const activeSwatch = computed(() => {
+  const shade = activeShade.value
+  if (shade === undefined) return undefined
+  const oklch = (shades.value as Record<number, string>)[shade]
+  if (!oklch) return undefined
+  const parsed = parseColor(oklch)
+  const rgb = parsed ? oklchToRgb(parsed) : undefined
+  return {
+    shade,
+    oklch,
+    hex: rgb ? rgbToHex(rgb) : '',
+    rgb: rgb ? `rgb(${rgb.map(channel => Math.round(channel * 255)).join(', ')})` : '',
+    pinned: pinnedShades.value.has(shade as Shade)
+  }
+})
+
+// Always-defined mirror; holds the last detail so content doesn't flash while
+// the popover animates closed.
+const lastDetail = ref({ shade: -1, oklch: '', hex: '', rgb: '', pinned: false })
+watch(activeSwatch, (value) => {
+  if (value) lastDetail.value = value
+})
+const swatchDetail = computed(() => activeSwatch.value ?? lastDetail.value)
+
+function onSwatchEnter(shade: number) {
+  // a stuck swatch blocks other hover-opens (clicking another migrates the stick)
+  if (stuckShade.value !== undefined && stuckShade.value !== shade) return
+  clearTimeout(hoverLeaveTimeout)
+  hoveredShade.value = shade
+}
+
+function onSwatchLeave() {
+  clearTimeout(hoverLeaveTimeout)
+  hoverLeaveTimeout = setTimeout(() => (hoveredShade.value = undefined), 150)
+}
+
+onUnmounted(() => clearTimeout(hoverLeaveTimeout))
+
+/** Click a swatch to keep its popover open (for editing); click again to release. */
+function toggleStuck(shade: number) {
+  stuckShade.value = stuckShade.value === shade ? undefined : shade
+}
+
+/** Pin the stop to whatever format was typed; keep the popover stuck open. */
+function commitSwatchColor(shade: number, value: string): boolean {
+  const ok = setPin(shade as Shade, value)
+  if (ok) stuckShade.value = shade
+  return ok
+}
+
+// A rejected value restates the field's canonical text, the box never shows
+// an unparseable string.
+function onColorCommit(shade: number, field: 'oklch' | 'hex' | 'rgb', event: Event) {
+  const input = event.target as HTMLInputElement
+  if (!commitSwatchColor(shade, input.value)) {
+    input.value = swatchDetail.value[field]
+  }
+}
+
+// Reka emits update:open(false) for trigger clicks too, clearing the stick
+// here would race toggleStuck. Only hover clears; toggleStuck/Esc release.
+function onSwatchOpenUpdate(shade: number, open: boolean) {
+  if (open) return
+  if (hoveredShade.value === shade) hoveredShade.value = undefined
+}
+
+function onSwatchEscape(shade: number) {
+  if (stuckShade.value === shade) stuckShade.value = undefined
+}
+
+// A closing hover-popover returns focus to its trigger tile, Reka reads that
+// focusin as focus-outside on the newly-opened one and dismisses it (hover A→B
+// closed B). Keep the focus return only for keyboard flows.
+function onSwatchCloseAutoFocus(event: Event) {
+  // the whole editor sits in the Colors panel's popper wrapper, only a swatch
+  // detail popover (has a copy button) marks a keyboard flow
+  const wrapper = document.activeElement?.closest('[data-reka-popper-content-wrapper]')
+  if (!wrapper?.querySelector('[aria-label^="Copy oklch"]')) {
+    event.preventDefault()
+  }
+}
+
+/** The strip element, every swatch popover anchors to it, not its tile. */
+const stripRef = useTemplateRef<HTMLElement>('stripRef')
+const stripEl = computed(() => stripRef.value ?? undefined)
+
+// Hue normalizes to 0–360 at seed, but a seam-crossing fit can leave points
+// outside, stretch the window once, at seed, or the drag clamp would snap a
+// merely-grabbed handle back into range.
+function hueWindow(hue: PaletteCurveParams['hue']) {
+  const points = [hue.y0, hue.y1, hue.p1y, hue.p2y]
+  return {
+    min: Math.min(0, Math.floor(Math.min(...points) / 10) * 10),
+    max: Math.max(360, Math.ceil(Math.max(...points) / 10) * 10)
+  }
+}
+// Fixed 1:1 windows, dragging never pans or rescales under the pointer.
+const windows = ref({
+  lightness: { min: 0, max: 1 },
+  chroma: { min: 0, max: 0.35 },
+  hue: hueWindow(params.hue)
+})
+
+// The colour field behind the curve: columns follow the ramp, rows sweep the
+// edited channel (top = max), each cell is the colour dragging there would give.
+const FIELD_COLUMNS = 24
+const FIELD_ROWS = 12
+const CHANNEL_KEYS = { lightness: 'l', chroma: 'c', hue: 'h' } as const
+
+// The 288 gamut-mapped cells are the biggest per-frame cost, feed a throttled
+// snapshot; the curve and stops track the pointer live, the field settles on release.
+const fieldCurves = ref<PaletteCurveParams>(structuredClone(toRaw(params)))
+const syncFieldCurves = useThrottleFn(() => {
+  fieldCurves.value = structuredClone(toRaw(params))
+}, 110, true, true)
+watch(params, () => syncFieldCurves(), { deep: true })
+
+const field = computed(() => {
+  const channel = tab.value
+  const { min, max } = windows.value[channel]
+  const curves = fieldCurves.value
+
+  // column i sampled AT x = i/(n-1), so endpoints sit under the endpoint controls
+  return Array.from({ length: FIELD_COLUMNS }, (_, columnIndex) => {
+    const x = columnIndex / (FIELD_COLUMNS - 1)
+    const base = {
+      l: sampleCurve(x, curves.lightness),
+      c: Math.max(0, sampleCurve(x, curves.chroma)),
+      h: sampleCurve(x, curves.hue)
+    }
+
+    return Array.from({ length: FIELD_ROWS }, (_, rowIndex) => {
+      const value = max - (rowIndex / (FIELD_ROWS - 1)) * (max - min)
+      return formatOklch(clampToGamut({ ...base, [CHANNEL_KEYS[channel]]: value }))
+    })
+  })
+})
+
+function normalizeHue(values: PaletteCurveParams) {
+  const points = [values.hue.y0, values.hue.y1, values.hue.p1y, values.hue.p2y]
+  const mean = points.reduce((sum, value) => sum + value, 0) / points.length
+  const shift = -360 * Math.floor(mean / 360)
+  if (shift !== 0) {
+    values.hue.y0 += shift
+    values.hue.y1 += shift
+    values.hue.p1y += shift
+    values.hue.p2y += shift
+  }
+}
+
+// The reactive apply reparses the custom-colours <style> and persists, fine
+// once, dominant at drag rate, so live drags ride the CSSOM fast path below
+// and only land here on the first edit and on release.
+const isDragging = ref(false)
+const customName = computed(() => `custom-${props.alias}`)
+
+function applyReactive() {
+  setPaletteFromCurve(props.alias, structuredClone(seedBase), { ...effects }, effectAmount.value, stopStep.value, plainPins(pins.value))
+  clearCssomPreview()
+}
+
+// Fast path: inline :root custom properties outrank the <style> rule, no
+// reparse, no persist. Only valid once the alias already resolves through
+// --color-custom-* (the first edit takes the reactive path to create it).
+function previewViaCssom() {
+  if (!import.meta.client) return
+  const root = document.documentElement.style
+  const ramp = shades.value
+  for (const shade of stopSet.value) root.setProperty(`--color-${customName.value}-${shade}`, ramp[shade]!)
+}
+
+// Sweeps every density's stops, the density may have changed since the
+// preview was written.
+function clearCssomPreview() {
+  if (!import.meta.client) return
+  const root = document.documentElement.style
+  for (const shade of SHADES_ALL) root.removeProperty(`--color-${customName.value}-${shade}`)
+}
+
+// Throttled (not debounced) so the theme streams while dragging; the trailing
+// call catches the release position.
+const throttledApply = useThrottleFn(() => {
+  if (!effectsDirty.value) {
+    seedBase = structuredClone(toRaw(params))
+  }
+  if (isDragging.value && active.value) {
+    previewViaCssom()
+  } else {
+    applyReactive()
+  }
+}, 60, true, true)
+
+// A density change drops pins on stops the new set doesn't emit, otherwise
+// they keep bending the ramp with no tile (25 and 10 are siblings, not nested).
+watch(stopStep, (step) => {
+  const stops = SHADE_SETS[step] as readonly number[]
+  const kept = pins.value.filter(pin => stops.includes(pin.shade))
+  if (kept.length !== pins.value.length) pins.value = kept
+  // drop popover state pointing at a tile that no longer renders
+  if (stuckShade.value !== undefined && !stops.includes(stuckShade.value)) stuckShade.value = undefined
+  if (hoveredShade.value !== undefined && !stops.includes(hoveredShade.value)) hoveredShade.value = undefined
+})
+
+// Any of these reshape the ramp. Programmatic writes (seeding, undo/redo sync)
+// wrap in ignoreUpdates so restores never fire an apply that clobbers them.
+const { ignoreUpdates } = watchIgnorable([() => params, pins, stopStep], () => {
+  throttledApply()
+}, { deep: true })
+
+function seed(values: PaletteCurveParams) {
+  const next = structuredClone(toRaw(values))
+  normalizeHue(next)
+  seedBase = structuredClone(next)
+  // A seed is never a user edit, an apply here would e.g. turn a stock ramp
+  // custom the instant the editor opens.
+  ignoreUpdates(() => {
+    Object.assign(effects, PALETTE_EFFECT_DEFAULTS)
+    effectAmount.value = 100
+    // a fresh fit is 11-stop; seedFromCurrent re-detects the density after
+    stopStep.value = 100
+    pins.value = []
+    Object.assign(params, next)
+  })
+  // this seed may cross the hue seam differently
+  windows.value.hue = hueWindow(next.hue)
+}
+
+function onDragStart() {
+  // Editing a curve commits the lens (look unchanged, sliders reset) so a
+  // later modifier edit can't throw the drag away.
+  if (effectsDirty.value) {
+    seedBase = structuredClone(toRaw(params))
+    Object.assign(effects, PALETTE_EFFECT_DEFAULTS)
+    effectAmount.value = 100
+  }
+  isDragging.value = true
+}
+
+function onDragEnd() {
+  isDragging.value = false
+  // Land once on the reactive path, a pending trailing throttle can't be
+  // relied on to fire after release; applyReactive clears the inline preview.
+  if (!effectsDirty.value) {
+    seedBase = structuredClone(toRaw(params))
+  }
+  // an inactive alias still wrote preview vars during the drag, clear directly
+  if (active.value) applyReactive()
+  else clearCssomPreview()
+}
+
+onUnmounted(() => {
+  // the fold can unmount mid-drag, don't strand inline preview vars
+  if (import.meta.client) clearCssomPreview()
+})
+
+/** Fit curves from whatever palette the alias currently shows. */
+function seedFromCurrent() {
+  const name = (appConfig.ui.colors as Record<string, string>)[props.alias]
+  if (!name) return
+
+  const source = paletteShades(name)
+  if (source) {
+    seed(fitPalette(source))
+    // keep a finer density detected on the source; ignored like the rest of the seed
+    const step = detectStopStep(source)
+    if (step !== 100) ignoreUpdates(() => (stopStep.value = step))
+  }
+}
+
+// External writes to the stored entry, reflect them here, lens included.
+watch(() => paletteParams.value[props.alias], (value) => {
+  if (!value || !('lightness' in value)) return
+  // Echo guard: skip only when curves, pins AND density all match, curves
+  // alone would swallow a pin- or density-only undo/redo.
+  const effective = applyPaletteEffects(pickCurves(value), value.effects, value.amount)
+  const curvesMatch = JSON.stringify(effective) === JSON.stringify(toRaw(params))
+  const pinsMatch = JSON.stringify(value.pins ?? []) === JSON.stringify(toRaw(pins.value))
+  const stepMatch = storedStopStep(value) === stopStep.value
+  if (curvesMatch && pinsMatch && stepMatch) return
+
+  seedBase = pickCurves(value)
+  normalizeHue(seedBase)
+  // must not echo back an apply that clobbers what's being restored
+  ignoreUpdates(() => {
+    Object.assign(effects, PALETTE_EFFECT_DEFAULTS, value.effects ?? {})
+    effectAmount.value = value.amount ?? 100
+    pins.value = value.pins ? plainPins(value.pins) : []
+    stopStep.value = storedStopStep(value)
+    Object.assign(params, applyPaletteEffects(seedBase, effects, effectAmount.value))
+  })
+  // a restored curve can cross the hue seam elsewhere
+  windows.value.hue = hueWindow(toRaw(params).hue)
+})
+
+// Open from the curves of the colour on screen, unless the editor already OWNS
+// curves for this alias, a preset's custom ramp is active but unowned, so it
+// still gets fitted. Popover state resets: the strip unmounts with the fold.
+watch([() => (appConfig.ui.colors as Record<string, string>)[props.alias], open], ([, isOpen]) => {
+  stuckShade.value = undefined
+  hoveredShade.value = undefined
+  const owned = paletteParams.value[props.alias]
+  if (isOpen && !(owned && 'lightness' in owned)) {
+    seedFromCurrent()
+  }
+})
+
+/* ---------------------------------------------------------- modifiers -- */
+
+const modifiersOpen = ref(false)
+
+const effectRows = [
+  { key: 'lightness', label: 'Lightness', min: -30, max: 30, step: 1, unit: '%' },
+  { key: 'contrast', label: 'Contrast', min: -50, max: 50, step: 1, unit: '%' },
+  { key: 'saturation', label: 'Saturation', min: -100, max: 200, step: 1, unit: '%' },
+  { key: 'hueShift', label: 'Hue', min: -180, max: 180, step: 1, unit: '°' }
+] as const
+
+/** Re-derive the displayed curves from the base, a user edit, live-applied. */
+function applyEffects() {
+  Object.assign(params, applyPaletteEffects(seedBase, effects, effectAmount.value))
+}
+
+const effectsDirty = computed(() => !isDefaultEffects(effects, effectAmount.value))
+
+function resetEffects() {
+  Object.assign(effects, PALETTE_EFFECT_DEFAULTS)
+  effectAmount.value = 100
+  applyEffects()
+}
+</script>
+
+<template>
+  <!-- unmount-on-hide: each open reseeds fresh -->
+  <UCollapsible :open="open">
+    <template #content>
+      <div class="mt-2.5 flex flex-col gap-2.5 pb-1">
+        <UTabs
+          v-model="tab"
+          :items="tabs"
+          :content="false"
+          size="xs"
+          color="neutral"
+        />
+
+        <div>
+          <ThemeStudioCurveEditor
+            v-model="params[tab]"
+            :label="tabs.find(({ value }) => value === tab)!.label"
+            :y-min="windows[tab].min"
+            :y-max="windows[tab].max"
+            :stop-colors="stopColors"
+            :stop-xs="stopXs"
+            :stop-pinned="stopPinned"
+            :stop-values="stopValues"
+            :actual-curve="actualCurve"
+            :field="field"
+            @drag-start="onDragStart"
+            @drag-end="onDragEnd"
+          />
+
+          <!-- Fixed 11:1 ratio so a denser ramp only narrows the tiles; the
+               single strip-anchored popover carries the details. -->
+          <div ref="stripRef" class="flex aspect-11/1 rounded-b-sm overflow-hidden ring ring-default">
+            <button
+              v-for="info in swatches"
+              :key="info.shade"
+              type="button"
+              class="relative flex-1"
+              :style="{ backgroundColor: info.oklch }"
+              :aria-label="`Shade ${info.shade}: ${info.oklch}`"
+              :aria-pressed="stuckShade === info.shade"
+              @click="toggleStuck(info.shade)"
+              @mouseenter="onSwatchEnter(info.shade)"
+              @mouseleave="onSwatchLeave"
+            >
+              <!-- past 19 stops a tile is narrower than the icon, use a hairline -->
+              <template v-if="pinnedShades.has(info.shade)">
+                <UIcon
+                  v-if="stopStep >= 50"
+                  name="i-lucide-pin"
+                  class="absolute inset-0 m-auto size-2.5 pointer-events-none"
+                  :class="pinBadgeClass(info.shade, 'text')"
+                />
+                <span
+                  v-else
+                  class="absolute inset-0 mx-auto w-px pointer-events-none"
+                  :class="pinBadgeClass(info.shade, 'bg')"
+                />
+              </template>
+            </button>
+          </div>
+
+          <UPopover
+            arrow
+            :open="!!activeSwatch"
+            :reference="stripEl"
+            :content="{
+              side: 'right',
+              onEscapeKeyDown: () => onSwatchEscape(swatchDetail.shade),
+              onCloseAutoFocus: onSwatchCloseAutoFocus,
+              sideOffset: 0,
+              // hover-opened popovers must not steal focus; a stuck one takes
+              // it so Tab lands on the copy button and colour inputs
+              onOpenAutoFocus: stuckShade === swatchDetail.shade ? undefined : (event: Event) => event.preventDefault(),
+              // stuck means kept-open: clicks elsewhere (curve drags, sliders)
+              // must not dismiss, only Esc, unstick or another stick
+              onInteractOutside: stuckShade === swatchDetail.shade ? (event: Event) => event.preventDefault() : undefined,
+              onFocusOutside: stuckShade === swatchDetail.shade ? (event: Event) => event.preventDefault() : undefined
+            }"
+            @update:open="onSwatchOpenUpdate(swatchDetail.shade, $event)"
+          >
+            <template #content>
+              <div
+                class="p-2 text-xs font-mono flex flex-col gap-1.5 w-60"
+                @mouseenter="onSwatchEnter(swatchDetail.shade)"
+                @mouseleave="onSwatchLeave"
+              >
+                <div class="flex items-center justify-between gap-3 ps-2">
+                  <span class="font-semibold flex items-center gap-1.5">
+                    {{ swatchDetail.shade }}
+                    <span v-if="swatchDetail.pinned" class="text-[10px] font-normal text-primary">pinned</span>
+                  </span>
+
+                  <div class="flex items-center">
+                    <UTooltip text="Copy oklch">
+                      <UButton
+                        size="xs"
+                        color="neutral"
+                        square
+                        variant="ghost"
+                        :ui="{ leadingIcon: 'size-3' }"
+                        :icon="copiedShade === swatchDetail.shade ? 'i-lucide-copy-check' : 'i-lucide-copy'"
+                        :aria-label="`Copy oklch ${swatchDetail.oklch}`"
+                        @click="copySwatch(swatchDetail)"
+                      />
+                    </UTooltip>
+
+                    <UTooltip :text="swatchDetail.pinned ? 'Unpin colour' : 'Pin this colour exactly'">
+                      <UButton
+                        size="xs"
+                        color="neutral"
+                        square
+                        variant="ghost"
+                        active-color="primary"
+                        active-variant="ghost"
+                        :active="swatchDetail.pinned"
+                        :ui="{ leadingIcon: 'size-3' }"
+                        :icon="swatchDetail.pinned ? 'i-lucide-pin-off' : 'i-lucide-pin'"
+                        :aria-label="swatchDetail.pinned ? 'Unpin this colour' : 'Pin this colour exactly'"
+                        @click="togglePinExact(swatchDetail.shade)"
+                      />
+                    </UTooltip>
+                  </div>
+                </div>
+
+                <!-- paste any format into any field: it pins the stop to that colour -->
+                <UInput
+                  :model-value="swatchDetail.oklch"
+                  size="xs"
+                  variant="ghost"
+                  autocomplete="off"
+                  spellcheck="false"
+                  aria-label="OKLCH value"
+                  :ui="{ base: 'font-mono' }"
+                  @focus="stuckShade = swatchDetail.shade"
+                  @change="onColorCommit(swatchDetail.shade, 'oklch', $event)"
+                  @keydown.enter="($event.target as HTMLInputElement).blur()"
+                />
+                <div class="flex gap-1.5">
+                  <UInput
+                    :model-value="swatchDetail.hex"
+                    size="xs"
+                    variant="ghost"
+                    autocomplete="off"
+                    spellcheck="false"
+                    aria-label="Hex value"
+                    class="w-18"
+                    :ui="{ base: 'font-mono' }"
+                    @focus="stuckShade = swatchDetail.shade"
+                    @change="onColorCommit(swatchDetail.shade, 'hex', $event)"
+                    @keydown.enter="($event.target as HTMLInputElement).blur()"
+                  />
+                  <UInput
+                    :model-value="swatchDetail.rgb"
+                    size="xs"
+                    variant="ghost"
+                    autocomplete="off"
+                    spellcheck="false"
+                    aria-label="RGB value"
+                    class="flex-1"
+                    :ui="{ base: 'font-mono' }"
+                    @focus="stuckShade = swatchDetail.shade"
+                    @change="onColorCommit(swatchDetail.shade, 'rgb', $event)"
+                    @keydown.enter="($event.target as HTMLInputElement).blur()"
+                  />
+                </div>
+              </div>
+            </template>
+          </UPopover>
+        </div>
+
+        <!-- Modifiers recompute from the fitted base; the reset stops the
+             click so it doesn't toggle the fold. -->
+        <UCollapsible v-model:open="modifiersOpen">
+          <div class="flex items-center gap-1">
+            <UButton
+              label="Modifiers"
+              :icon="modifiersOpen ? 'i-lucide-chevron-down' : 'i-lucide-chevron-right'"
+              color="neutral"
+              variant="ghost"
+              size="sm"
+              block
+              class="flex-1 justify-start"
+            />
+            <!-- rides this row so it never overlaps the curve handles; its
+                 click must not toggle the fold -->
+            <UTooltip text="Shade interval">
+              <USelect
+                v-model="stopStep"
+                :items="stopItems"
+                size="sm"
+                variant="ghost"
+                class="shrink-0"
+                @click.stop
+              />
+            </UTooltip>
+            <!-- modifiers live outside the doc, so defaults = the preset;
+                 only the dirty styling mirrors the section resets -->
+            <UTooltip :text="effectsDirty ? 'Reset modifiers' : 'No modifiers active'">
+              <UButton
+                icon="i-lucide-rotate-ccw"
+                color="neutral"
+                variant="ghost"
+                :active="effectsDirty"
+                active-variant="outline"
+                size="sm"
+                :disabled="!effectsDirty"
+                aria-label="Reset modifiers"
+                @click.stop="resetEffects"
+              />
+            </UTooltip>
+          </div>
+
+          <template #content>
+            <div class="flex flex-col gap-1.5 pt-2 px-1">
+              <ThemeStudioRow
+                v-model="effectAmount"
+                control="slider"
+                label="Effect"
+                icon="i-lucide-eye"
+                :min="0"
+                :max="200"
+                :step="1"
+                unit="%"
+                @update:model-value="applyEffects()"
+              />
+
+              <ThemeStudioRow
+                v-for="row in effectRows"
+                :key="row.key"
+                v-model="effects[row.key]"
+                control="slider"
+                :label="row.label"
+                :min="row.min"
+                :max="row.max"
+                :step="row.step"
+                :unit="row.unit"
+                @update:model-value="applyEffects()"
+              />
+            </div>
+          </template>
+        </UCollapsible>
+      </div>
+    </template>
+  </UCollapsible>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioPicker.vue b/docs/app/components/theme-studio/ThemeStudioPicker.vue
new file mode 100644
index 0000000000..54f70c1b24
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioPicker.vue
@@ -0,0 +1,98 @@
+<script setup lang="ts">
+/**
+ * The header's theme popover: a grid of preset swatches with the full studio
+ * one click away. Picking only, everything else (export, reset, the rest of
+ * the axes) lives in the studio. The header drops this on /theme, where the
+ * studio's own toolbar covers it.
+ */
+import { themeSwatchStyle, keepPanels } from '../../utils/theme/studio'
+
+const { track } = useAnalytics()
+const studioIcons = useStudioIcons()
+
+const open = ref(false)
+
+// The persisted theme is client-only, gate the selection on mount so
+// hydration doesn't adopt a checked row the server never rendered.
+const mounted = ref(false)
+onMounted(() => (mounted.value = true))
+
+watch(open, (isOpen) => {
+  if (isOpen) {
+    track('Theme Picker Opened')
+  }
+})
+
+const { presets, selectedPreset, applyPreset } = useThemeStudio()
+
+const presetTiles = computed(() => presets.map(preset => ({
+  id: preset.id,
+  label: preset.name,
+  icon: preset.icon,
+  swatch: themeSwatchStyle(preset.doc)
+})))
+
+const selected = computed({
+  get: () => (mounted.value ? selectedPreset.value : undefined),
+  set: (id: string | undefined) => {
+    const preset = presets.find(entry => entry.id === id)
+    if (preset) applyPreset(preset)
+  }
+})
+</script>
+
+<template>
+  <UPopover
+    v-model:open="open"
+    :content="{ onInteractOutside: keepPanels }"
+    :ui="{ content: 'divide-y divide-default w-56' }"
+  >
+    <UTooltip text="Theme">
+      <UButton
+        :icon="studioIcons.themes"
+        color="neutral"
+        :variant="open ? 'soft' : 'ghost'"
+        square
+        aria-label="Theme"
+      />
+    </UTooltip>
+
+    <template #content>
+      <UListbox
+        v-model="selected"
+        :items="presetTiles"
+        value-key="id"
+        :ui="{
+          root: () => 'p-1.5',
+          content: 'max-h-none',
+          group: 'p-0 grid grid-cols-3',
+          item: 'flex-col items-center gap-1.5 data-[state=checked]:before:bg-elevated hover:data-[state=checked]:before:bg-elevated',
+          itemWrapper: 'min-w-0 w-full text-center',
+          itemLabel: 'w-full truncate text-[11px]',
+          itemTrailing: 'hidden'
+        }"
+      >
+        <template #item-leading="{ item }">
+          <span
+            class="flex items-center justify-center size-8 rounded-full bg-(image:--swatch-light) dark:bg-(image:--swatch-dark)"
+            :style="item.swatch"
+          >
+            <UIcon :name="item.icon" class="size-5 text-(--swatch-ink-light) dark:text-(--swatch-ink-dark)" />
+          </span>
+        </template>
+      </UListbox>
+
+      <div class="p-3">
+        <UButton
+          block
+          label="Edit theme"
+          :icon="studioIcons.themes"
+          color="neutral"
+          variant="outline"
+          to="/theme"
+          @click="open = false"
+        />
+      </div>
+    </template>
+  </UPopover>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioPresetMenu.vue b/docs/app/components/theme-studio/ThemeStudioPresetMenu.vue
new file mode 100644
index 0000000000..0dec323cf8
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioPresetMenu.vue
@@ -0,0 +1,132 @@
+<script setup lang="ts">
+import type { ThemeDoc } from '../../utils/theme/engine'
+import { themeIcons } from '../../utils/theme/icons'
+import { themeChipStyle, keepPanels, loadFontPreviews } from '../../utils/theme/studio'
+
+/** The presets trigger and its listbox: the label names the applied preset. */
+defineProps<{
+  /** Set where the trigger carries no visible label of its own. */
+  tooltip?: string
+}>()
+
+const { presets, selectedPreset, applyPreset } = useThemeStudio()
+const { fonts } = useTheme()
+const appConfig = useAppConfig()
+const studioIcons = useStudioIcons()
+
+/** Exposed so the toolbar can pin itself while the menu is open. */
+const open = defineModel<boolean>('open', { default: false })
+
+// The persisted preset (and any persisted edits) are client-only, resolve
+// the label after mount so hydration matches the server's fallback.
+const mounted = ref(false)
+onMounted(() => {
+  mounted.value = true
+  // the rows render their own font names, load the faces once
+  loadFontPreviews(fonts.map(entry => entry.name))
+})
+
+// the toolbar stays open when a click lands on its own chrome
+const onKeepPanels = keepPanels
+
+// Edits deliberately don't clear the preset name (the controls that changed
+// go primary to carry divergence); 'Custom' only when preset-less but
+// diverged from stock.
+const activeEntry = computed(() => (mounted.value
+  ? presets.find(preset => preset.id === selectedPreset.value)
+  : undefined))
+
+const presetLabel = computed(() => {
+  if (!mounted.value) return 'Presets'
+  return activeEntry.value ? activeEntry.value.name : 'Custom'
+})
+
+/** Its row's own glyph; the swatch book stands in when no preset is behind it. */
+const presetIcon = computed(() => activeEntry.value?.icon ?? studioIcons.themes)
+
+/** A taste of the doc's icon set (its own, or the default lucide). */
+function iconSamples(doc: ThemeDoc): string[] {
+  const sets = themeIcons as Record<string, Record<string, string>>
+  const set = sets[doc.icons ?? 'lucide'] ?? sets.lucide!
+  // upload, search and folder vary the most between the sets
+  return ['upload', 'search', 'folder'].map(key => set[key]!)
+}
+
+const presetItems = computed(() => presets.map(preset => ({
+  id: preset.id,
+  label: preset.name,
+  chipIcon: preset.icon,
+  themeChip: themeChipStyle(preset.doc),
+  font: preset.doc.font?.sans ?? 'Public Sans',
+  iconSamples: iconSamples(preset.doc)
+})))
+
+const selected = computed({
+  get: () => mounted.value ? selectedPreset.value : undefined,
+  set: (id: string | undefined) => {
+    const preset = presets.find(entry => entry.id === id)
+    if (preset) {
+      applyPreset(preset)
+      open.value = false
+    }
+  }
+})
+</script>
+
+<template>
+  <div class="flex gap-2">
+    <UPopover
+      v-model:open="open"
+      :content="{ align: 'start', onInteractOutside: onKeepPanels }"
+      class="flex-1 min-w-0"
+    >
+      <UTooltip :text="tooltip" :disabled="!tooltip">
+        <UButton
+          :label="presetLabel"
+          :icon="presetIcon"
+          :trailing-icon="appConfig.ui.icons.chevronDown"
+          color="neutral"
+          variant="outline"
+          block
+          :ui="{ leadingIcon: 'text-primary' }"
+        />
+      </UTooltip>
+
+      <template #content>
+        <UListbox
+          v-model="selected"
+          :items="presetItems"
+          value-key="id"
+          class="w-80"
+          :ui="{
+            root: 'ring-0 rounded-md',
+            content: 'max-h-96',
+            item: 'gap-3'
+          }"
+        >
+          <template #item-leading="{ item }">
+            <span
+              class="flex items-center justify-center size-10 rounded-md ring ring-default shrink-0 bg-[image:var(--chip-bg-light)] dark:bg-[image:var(--chip-bg-dark)]"
+              :style="item.themeChip"
+            >
+              <UIcon :name="item.chipIcon" class="size-4 text-(--chip-icon-light) dark:text-(--chip-icon-dark)" />
+            </span>
+          </template>
+
+          <!-- the doc's font in its own face and a taste of its icon set -->
+          <template #item-description="{ item }">
+            <span class="flex items-center gap-2 pt-0.5">
+              <span class="shrink-0 text-xs text-muted truncate" :style="{ fontFamily: `'${item.font}', sans-serif` }">{{ item.font }}</span>
+
+              <span class="text-dimmed select-none">·</span>
+
+              <span class="flex items-center gap-1 shrink-0">
+                <UIcon v-for="name in item.iconSamples" :key="name" :name="name" class="size-3 text-dimmed" />
+              </span>
+            </span>
+          </template>
+        </UListbox>
+      </template>
+    </UPopover>
+  </div>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioRadiusOptions.vue b/docs/app/components/theme-studio/ThemeStudioRadiusOptions.vue
new file mode 100644
index 0000000000..ea97a7e728
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioRadiusOptions.vue
@@ -0,0 +1,47 @@
+<script setup lang="ts">
+import { keepPanels } from '../../utils/theme/studio'
+
+/**
+ * The radius picker. Seven discrete stops as a segmented row was wider than
+ * every other toolbar control put together, so it reads them out of a select
+ * like the font and icon pickers beside it.
+ */
+defineProps<{ tooltip?: string, dirty?: boolean }>()
+
+/** Exposed so the toolbar can pin itself while the list is open. */
+const open = defineModel<boolean>('open', { default: false })
+
+// The tooltip has to wrap the trigger, so it takes the root; forward the
+// caller's class past it or the toolbar's width lands on nothing.
+defineOptions({ inheritAttrs: false })
+
+const { radius, radiuses } = useTheme()
+const studioIcons = useStudioIcons()
+
+// `--ui-radius` is a rem length, so the stop IS the label.
+const items = radiuses.map(value => ({ label: `${value}rem`, value }))
+</script>
+
+<template>
+  <UTooltip :text="tooltip" :disabled="!tooltip">
+    <USelectMenu
+      v-model="radius"
+      v-model:open="open"
+      :items="items"
+      value-key="value"
+      :icon="studioIcons.radius"
+      :content="{ onInteractOutside: keepPanels }"
+      :search-input="false"
+      :color="dirty ? 'primary' : 'neutral'"
+      :highlight="dirty"
+      variant="outline"
+      :ui="{
+        base: dirty && 'ring-primary/50 text-primary',
+        leadingIcon: dirty && 'text-primary',
+        trailingIcon: dirty && 'text-primary'
+      }"
+      aria-label="Radius"
+      v-bind="$attrs"
+    />
+  </UTooltip>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioRow.vue b/docs/app/components/theme-studio/ThemeStudioRow.vue
new file mode 100644
index 0000000000..cd273a49f9
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioRow.vue
@@ -0,0 +1,225 @@
+<script setup lang="ts">
+import { SHADE_LADDER } from '../../utils/theme/engine'
+import type { ShadeStop } from '../../utils/theme/engine'
+import type { ChipProps } from '@nuxt/ui'
+
+/** Every settings row in every panel: label, then the control, on one 28px line. */
+export interface RowSelectItem {
+  label: string
+  value: string
+  defaultTag?: boolean
+  chip?: ChipProps
+}
+
+const props = withDefaults(defineProps<{
+  control?: 'slider' | 'shade' | 'switch' | 'select' | 'custom'
+  label?: string
+  /** Replaces the label text in the column. */
+  icon?: string
+  /** The control's own glyph, not the label's. */
+  controlIcon?: string
+  ariaLabel?: string
+
+  min?: number
+  max?: number
+  step?: number
+  /** Readout suffix (%, px, rem, °). */
+  unit?: string
+  /** Palette the shade stops resolve against. */
+  chip?: string
+  mode?: 'light' | 'dark'
+  /** Fine ramps swap in the wider 21-stop ladder. */
+  ladder?: readonly ShadeStop[]
+  /** `reset` deletes the override, writing the default would pin a lookalike. */
+  resettable?: boolean
+  dirty?: boolean
+  items?: RowSelectItem[]
+}>(), {
+  control: 'slider',
+  min: 0,
+  step: 1,
+  ladder: () => SHADE_LADDER
+})
+
+// Optional: a `custom` row's slot brings its own control.
+const model = defineModel<any>()
+
+const emit = defineEmits<{ reset: [] }>()
+
+const slots = defineSlots<{
+  /** The control area, for `custom`. */
+  default: () => any
+  /** Leading content in a `select` trigger. */
+  leading: () => any
+}>()
+
+const shade = computed(() => props.control === 'shade')
+// Shade rows span the ladder; plain rows use the caller's max.
+const sliderMax = computed(() => (shade.value ? props.ladder.length - 1 : props.max ?? SHADE_LADDER.length - 1))
+const stop = computed(() => props.ladder[model.value as number])
+const sliderColor = computed(() => {
+  if (!shade.value) return undefined
+  // the ladder's ends are literals no ramp variable can express
+  return stop.value === 'white' || stop.value === 'black' ? stop.value : `var(--color-${props.chip}-${stop.value})`
+})
+
+// ×1000 turns the lightness difference into a hard black/white switch.
+const contrastColor = computed(() => shade.value
+  ? `oklch(from ${sliderColor.value} clamp(0.12, (0.66 - l) * 1000, 0.95) 0 h / 0.65)`
+  : undefined)
+
+const stopItems = computed(() => props.ladder.map((entry, index) => ({ label: String(entry), value: String(index) })))
+
+// USelect speaks strings; the value is an index into the ladder.
+const stopModel = computed({
+  get: () => String(model.value ?? 0),
+  set: (value: string) => (model.value = Number(value))
+})
+
+/** `0.25rem` reads as `.25rem`, the leading zero is noise at this width. */
+const display = computed(() => `${String(model.value).replace(/^(-?)0\./, '$1.')}${props.unit ?? ''}`)
+
+// Only the range clamps, typed between-step values are deliberate.
+function clamp(raw: number): number {
+  return Number(Math.min(sliderMax.value, Math.max(props.min, raw)).toFixed(4))
+}
+
+// The readout doubles as an input: type, or nudge with arrows (Shift ×10).
+function onReadoutKeydown(event: KeyboardEvent) {
+  if (event.key === 'Enter') {
+    (event.target as HTMLInputElement).blur()
+    return
+  }
+  if (event.key !== 'ArrowUp' && event.key !== 'ArrowDown') return
+  event.preventDefault()
+  const steps = (event.key === 'ArrowUp' ? 1 : -1) * (event.shiftKey ? 10 : 1)
+  model.value = clamp((model.value as number) + steps * props.step)
+}
+
+function commitReadout(event: Event) {
+  const input = event.target as HTMLInputElement
+  const parsed = Number.parseFloat(input.value)
+  if (!Number.isNaN(parsed)) {
+    model.value = clamp(parsed)
+  }
+  // A rejected or same-value commit doesn't re-render, restate the text.
+  input.value = display.value
+}
+
+// Switch labels read as sentences: natural width, toggle pushed to the end.
+const spread = computed(() => props.control === 'switch')
+
+const showTextLabel = computed(() => !props.icon && !shade.value)
+</script>
+
+<template>
+  <UFormField
+    :label="showTextLabel ? label : undefined"
+    orientation="horizontal"
+    size="xs"
+    :style="sliderColor ? { '--slider-color': sliderColor, '--slider-contrast': contrastColor } : undefined"
+    :ui="{
+      /* the row contract: 28px, matching a size-sm button */
+      root: 'flex items-center gap-2 min-h-7',
+      wrapper: spread ? 'shrink-0' : 'w-13 shrink-0',
+      /* truncate text labels only, it would clip the shade chip's ring */
+      label: `w-full text-muted font-normal select-none${showTextLabel && !spread ? ' truncate' : ''}`,
+      container: `flex-1 flex items-center gap-2 mt-0${spread ? ' justify-end' : ''}`
+    }"
+  >
+    <template v-if="icon || shade" #label>
+      <UIcon v-if="icon" :name="icon" class="size-3.5 text-muted" />
+
+      <span v-else class="flex items-center gap-2 w-full">
+        <UIcon :name="mode === 'light' ? 'i-lucide-sun' : 'i-lucide-moon'" class="size-3.5 text-muted shrink-0" />
+        <span class="size-3.5 grow rounded-full bg-(--slider-color) ring ring-(--slider-contrast) me-px" />
+      </span>
+    </template>
+
+    <template v-if="control === 'slider' || control === 'shade'">
+      <USlider
+        v-model="model"
+        :min="min"
+        :max="sliderMax"
+        :step="step"
+        color="primary"
+        size="xs"
+        :aria-label="ariaLabel ?? label ?? mode"
+      />
+
+      <!-- Fixed set of stops, so the readout picks rather than types. -->
+      <USelect
+        v-if="shade"
+        v-model="stopModel"
+        :items="stopItems"
+        size="xs"
+        color="neutral"
+        variant="none"
+        class="w-10 shrink-0"
+        :ui="{
+          /* bare until hovered, when a ring says it's editable */
+          /* pe-7 is reserved for a chevron we hide, and outranks px-* */
+          base: 'px-1 pe-1 text-xs justify-end font-mono text-dimmed focus:text-default focus:ring-1 ring-inset transition-all focus:ring-default hover:ring-1 ring-default',
+          value: 'truncate',
+          trailing: 'hidden',
+          /* the menu would inherit the readout's 10-wide trigger */
+          content: 'w-auto min-w-20',
+          item: 'text-xs font-mono'
+        }"
+        :aria-label="`${label ?? mode} shade`"
+      />
+
+      <!-- No v-model: partial keystrokes must not live-apply. -->
+      <UInput
+        v-if="!shade"
+        :model-value="display"
+        type="text"
+        inputmode="decimal"
+        autocomplete="off"
+        variant="none"
+        size="xs"
+        class="w-10 shrink-0"
+        :ui="{ base: 'px-1 text-xs text-right font-mono text-dimmed focus:text-default focus:ring-1 ring-inset transition-all focus:ring-default hover:ring-1 ring-default' }"
+        :aria-label="`${label ?? 'Value'} (arrow keys to adjust, Shift for ×10)`"
+        @keydown="onReadoutKeydown"
+        @change="commitReadout"
+      />
+
+      <UButton
+        v-if="resettable"
+        icon="i-lucide-rotate-ccw"
+        size="xs"
+        color="neutral"
+        variant="ghost"
+        :active="dirty"
+        active-variant="outline"
+        :disabled="!dirty"
+        :ui="{ leadingIcon: 'size-3' }"
+        :aria-label="`Reset ${label ?? mode}`"
+        @click="emit('reset')"
+      />
+    </template>
+
+    <USwitch
+      v-else-if="control === 'switch'"
+      v-model="model"
+      size="sm"
+      :aria-label="ariaLabel ?? label"
+    />
+
+    <ThemeStudioDefaultSelect
+      v-else-if="control === 'select'"
+      v-model="model"
+      :items="items ?? []"
+      :icon="controlIcon"
+      :aria-label="ariaLabel ?? label"
+      class="flex-1"
+    >
+      <template v-if="!!slots.leading" #leading>
+        <slot name="leading" />
+      </template>
+    </ThemeStudioDefaultSelect>
+
+    <slot v-else />
+  </UFormField>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioSection.vue b/docs/app/components/theme-studio/ThemeStudioSection.vue
new file mode 100644
index 0000000000..26dc1a07ba
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioSection.vue
@@ -0,0 +1,136 @@
+<script setup lang="ts">
+/** One settings section. Header buttons stop the click so they never fold it. */
+import type { SectionKey } from '../../utils/theme/engine'
+import { SECTION_DEPTH } from '../../utils/theme/studio'
+
+const props = withDefaults(defineProps<{
+  /** Omit on a static section for a bare group, no header drawn. */
+  label?: string
+  /** Docs page the header's help icon links to */
+  helpTo?: string
+  /** The ThemeDoc slice(s) this fold owns; drives its reset button. */
+  sectionKey?: SectionKey | SectionKey[]
+  /** Reset a section the doc has no slice for, the caller says when it's dirty. */
+  resettable?: boolean
+  resetDirty?: boolean
+  /* These three default from depth, pass one only to override it. */
+  defaultOpen?: boolean
+  collapsible?: boolean
+  separator?: boolean
+}>(), {
+  // absent optional booleans cast to false, which would read as an override
+  defaultOpen: undefined,
+  collapsible: undefined,
+  separator: undefined,
+  resettable: undefined,
+  resetDirty: undefined
+})
+
+const emit = defineEmits<{ reset: [] }>()
+
+const { sectionDirty, resetSection } = useThemeStudio()
+
+// A section resets either its doc slice or whatever the caller wired up.
+const showReset = computed(() => !!props.sectionKey || !!props.resettable)
+const dirty = computed(() => (props.sectionKey ? sectionDirty(props.sectionKey).value : !!props.resetDirty))
+
+function reset() {
+  if (props.sectionKey) resetSection(props.sectionKey)
+  else emit('reset')
+}
+
+const slots = defineSlots<{
+  default: () => any
+  /** Controls beside the trigger (edit/adjust toggles). */
+  actions: () => any
+}>()
+
+// Top level folds open, the layer under it folds shut, leaves are plain groups.
+const depth = inject(SECTION_DEPTH, 0)
+provide(SECTION_DEPTH, depth + 1)
+
+// Nothing in the header means it's a bare group, a chevron with no label
+// beside it is a trigger for nothing.
+const hasHeader = computed(() => !!(props.label || props.helpTo || showReset.value || slots.actions))
+const collapsible = computed(() => props.collapsible ?? (depth < 2 && hasHeader.value))
+const separator = computed(() => props.separator ?? depth < 2)
+
+const open = ref(collapsible.value ? (props.defaultOpen ?? depth === 0) : true)
+
+// A first nested section sits right under the header, nothing above it to
+// separate from. Scoped to sections: any other first child keeps its padding.
+// Padding rides an inner box, never the animated one: padding can't collapse
+// below itself, so a fold with its own padding animates down to that padding
+// and then drops it in one frame when it unmounts.
+const contentClass = 'pt-2 flex flex-col gap-2 [&>[data-studio-section]:first-child]:border-t-0 [&>[data-studio-section]:first-child]:mt-0 [&>[data-studio-section]:first-child]:pt-0'
+</script>
+
+<template>
+  <UCollapsible
+    v-model:open="open"
+    data-studio-section
+    :disabled="!collapsible"
+    :class="[
+      /* Space above a rule is the parent's gap, below it this padding. */
+      depth === 0 ? 'p-4' : (separator ? 'pt-2' : ''),
+      separator && 'border-t border-default'
+    ]"
+    :ui="{ content: 'overflow-hidden' }"
+  >
+    <div v-if="hasHeader" class="flex items-center gap-1">
+      <!-- The leading chevron tells a fold apart from a select. -->
+      <UButton
+        :label="label"
+        :icon="collapsible ? (open ? 'i-lucide-chevron-down' : 'i-lucide-chevron-right') : undefined"
+        :as="collapsible ? undefined : 'span'"
+        color="neutral"
+        variant="ghost"
+        size="sm"
+        block
+        class="justify-start flex-1"
+        :class="{ 'px-0': !collapsible }"
+        :tabindex="collapsible ? undefined : -1"
+        :ui="collapsible ? undefined : {
+          /* a heading shouldn't tint on hover, press or open */
+          base: 'cursor-default select-none hover:bg-transparent active:bg-transparent data-[state=open]:bg-transparent focus:outline-none focus-visible:outline-none focus-visible:ring-0'
+        }"
+      />
+
+      <UTooltip v-if="helpTo" text="Docs">
+        <UButton
+          :to="helpTo"
+          size="sm"
+          color="neutral"
+          variant="ghost"
+          icon="i-lucide-help-circle"
+          aria-label="Documentation for this setting"
+          @click.stop
+        />
+      </UTooltip>
+
+      <UTooltip v-if="showReset" :text="dirty ? 'Reset to preset' : 'Matches the preset'">
+        <UButton
+          size="sm"
+          color="neutral"
+          variant="ghost"
+          :active="dirty"
+          active-color="primary"
+          icon="i-lucide-rotate-ccw"
+          :disabled="!dirty"
+          :aria-label="label ? `Reset ${label} to preset` : 'Reset to preset'"
+          @click.stop="reset"
+        />
+      </UTooltip>
+
+      <div v-if="!!slots.actions" class="flex items-center gap-1" @click.stop="open = true">
+        <slot name="actions" />
+      </div>
+    </div>
+
+    <template #content>
+      <div :class="contentClass">
+        <slot />
+      </div>
+    </template>
+  </UCollapsible>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioShadeGroup.vue b/docs/app/components/theme-studio/ThemeStudioShadeGroup.vue
new file mode 100644
index 0000000000..89649e0d9d
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioShadeGroup.vue
@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import { SHADE_LADDER } from '../../utils/theme/engine'
+import type { ShadeStop } from '../../utils/theme/engine'
+
+/**
+ * A section of per-mode shade sliders that reset as one group, the sliders
+ * carry their own dirty state, so no call site has to fold it by hand.
+ */
+export interface ShadeSlider {
+  model: { value: number }
+  dirty: { value: boolean }
+  reset: () => void
+}
+
+const props = withDefaults(defineProps<{
+  label?: string
+  /** Omit for a group whose rows come from its slot instead. */
+  sliders?: Record<'light' | 'dark', ShadeSlider>
+  /** Palette the stops resolve against. */
+  chip?: string
+  ladder?: readonly ShadeStop[]
+  separator?: boolean
+  /** A colour source with no shades keeps its group, minus the sliders. */
+  showRows?: boolean
+}>(), {
+  // an empty record rather than undefined: a `?? {}` in the v-for widens the
+  // item to never, and a Partial makes every row possibly-undefined
+  sliders: () => ({}) as Record<'light' | 'dark', ShadeSlider>,
+  separator: undefined,
+  showRows: true,
+  ladder: () => SHADE_LADDER
+})
+
+const rows = computed(() => Object.values(props.sliders))
+
+const dirty = computed(() => rows.value.some(slider => slider.dirty.value))
+
+function reset() {
+  rows.value.forEach(slider => slider.reset())
+}
+</script>
+
+<template>
+  <ThemeStudioSection
+    :label="label"
+    :separator="separator"
+    :resettable="!!rows.length"
+    :reset-dirty="dirty"
+    @reset="reset"
+  >
+    <!-- whatever picks the colour these stops ride -->
+    <slot />
+
+    <ThemeStudioRow
+      v-for="(slider, mode) in sliders"
+      v-show="showRows"
+      :key="mode"
+      v-model="slider.model.value"
+      control="shade"
+      :mode="mode"
+      :chip="chip"
+      :ladder="ladder"
+    />
+  </ThemeStudioSection>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioShareModal.vue b/docs/app/components/theme-studio/ThemeStudioShareModal.vue
new file mode 100644
index 0000000000..3d8d82efb8
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioShareModal.vue
@@ -0,0 +1,159 @@
+<script setup lang="ts">
+import { importTheme, isDefaultTheme } from '../../utils/theme/engine'
+
+/**
+ * The shared import/export modal, plain toolbar buttons open it in either
+ * mode. Export shows the generated files with copy buttons; import parses
+ * a paste of the same two files back into editable settings.
+ */
+const open = defineModel<boolean>('open', { default: false })
+const mode = defineModel<'import' | 'export'>('mode', { default: 'export' })
+
+const { applyDoc, clearActivePreset } = useThemeStudio()
+const { exportCSS, exportConfig, configLabel, hasCSSChanges, hasConfigChanges } = useTheme()
+const { track } = useAnalytics()
+const { copy: copyCSS, copied: copiedCSS } = useClipboard()
+const { copy: copyConfig, copied: copiedConfig } = useClipboard()
+
+const css = ref('')
+const config = ref('')
+const skipped = ref<string[]>([])
+const imported = ref(false)
+const empty = ref(false)
+
+watch([open, mode], () => {
+  skipped.value = []
+  imported.value = false
+  empty.value = false
+  // Export fills the panes with the generated files; import starts blank.
+  css.value = mode.value === 'export' && open.value ? exportCSS() : ''
+  config.value = mode.value === 'export' && open.value ? exportConfig() : ''
+})
+
+function runImport() {
+  const result = importTheme({ css: css.value, config: config.value })
+  skipped.value = result.skipped
+  empty.value = isDefaultTheme(result.doc)
+  imported.value = false
+
+  if (!empty.value) {
+    applyDoc(result.doc)
+    // an imported doc replaces the whole theme, the old preset is no
+    // longer the baseline the dirty indicators should measure against
+    clearActivePreset()
+    imported.value = true
+    track('Theme Imported', { skipped: result.skipped.length })
+  }
+}
+</script>
+
+<template>
+  <UModal
+    v-model:open="open"
+    :title="mode === 'export' ? 'Export theme' : 'Import theme'"
+    :description="mode === 'export'
+      ? 'Copy only what you changed, everything else stays inherited from Nuxt UI defaults.'
+      : 'Paste an exported main.css and/or app.config.ts, the studio parses it back into editable settings.'"
+    :ui="{ content: 'max-w-3xl' }"
+  >
+    <template #body>
+      <div class="flex flex-col gap-4">
+        <UAlert
+          v-if="mode === 'export' && !hasCSSChanges && !hasConfigChanges"
+          title="No changes yet"
+          description="You are on the default theme. Tweak something and come back."
+          icon="i-lucide-info"
+          color="neutral"
+          variant="subtle"
+        />
+
+        <div class="grid grid-cols-1 lg:grid-cols-2 gap-4">
+          <div v-for="pane in (['css', 'config'] as const)" :key="pane" class="flex flex-col gap-2 min-w-0">
+            <div class="flex items-center justify-between gap-2">
+              <p class="text-xs font-semibold text-muted font-mono">
+                {{ pane === 'css' ? 'main.css' : configLabel }}
+              </p>
+
+              <UButton
+                v-if="mode === 'export'"
+                size="xs"
+                color="neutral"
+                variant="ghost"
+                :icon="(pane === 'css' ? copiedCSS : copiedConfig) ? 'i-lucide-copy-check' : 'i-lucide-copy'"
+                :aria-label="pane === 'css' ? 'Copy CSS' : 'Copy config'"
+                @click="pane === 'css'
+                  ? (copyCSS(css), track('Theme Exported', { type: 'CSS' }))
+                  : (copyConfig(config), track('Theme Exported', { type: 'Config' }))"
+              />
+            </div>
+
+            <pre v-if="mode === 'export'" class="text-xs font-mono bg-muted rounded-md p-3 overflow-x-auto max-h-96 whitespace-pre">{{ pane === 'css' ? css : config }}</pre>
+
+            <UTextarea
+              v-else-if="pane === 'css'"
+              v-model="css"
+              :rows="10"
+              placeholder="@import &quot;tailwindcss&quot;;&#10;@import &quot;@nuxt/ui&quot;;&#10;…"
+              class="w-full font-mono"
+              variant="subtle"
+              :ui="{ base: 'text-xs' }"
+            />
+
+            <UTextarea
+              v-else
+              v-model="config"
+              :rows="10"
+              variant="subtle"
+              placeholder="export default defineAppConfig({&#10;  ui: { … }&#10;})"
+              class="w-full font-mono"
+              :ui="{ base: 'text-xs' }"
+            />
+          </div>
+        </div>
+
+        <UAlert
+          v-if="imported"
+          title="Theme imported"
+          :description="skipped.length ? 'Applied, a few lines were outside the theme schema and were skipped (listed below).' : 'Applied. Every line was understood.'"
+          icon="i-lucide-check"
+          color="success"
+          variant="subtle"
+        />
+
+        <UAlert
+          v-else-if="empty"
+          title="Nothing to import"
+          description="No theme settings were recognized in the pasted content."
+          icon="i-lucide-info"
+          color="warning"
+          variant="subtle"
+        />
+
+        <div v-if="skipped.length" class="flex flex-col gap-1">
+          <p class="text-xs font-semibold text-muted">
+            Skipped
+          </p>
+          <pre class="text-xs font-mono bg-muted rounded-md p-3 overflow-x-auto max-h-40 whitespace-pre">{{ skipped.join('\n') }}</pre>
+        </div>
+      </div>
+    </template>
+
+    <template v-if="mode === 'import'" #footer>
+      <div class="flex justify-end gap-2 w-full">
+        <UButton
+          label="Cancel"
+          color="neutral"
+          variant="ghost"
+          @click="open = false"
+        />
+        <UButton
+          label="Import"
+          icon="i-lucide-upload"
+          color="neutral"
+          :disabled="!css.trim() && !config.trim()"
+          @click="runImport"
+        />
+      </div>
+    </template>
+  </UModal>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioShuffleButton.vue b/docs/app/components/theme-studio/ThemeStudioShuffleButton.vue
new file mode 100644
index 0000000000..175b3cb126
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioShuffleButton.vue
@@ -0,0 +1,133 @@
+<script setup lang="ts">
+/** Rolls a random theme, the die tumbling through faces as it goes. */
+defineProps<{
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+}>()
+
+const { shuffle } = useThemeStudio()
+const { icon: iconSet } = useTheme()
+const studioIcons = useStudioIcons()
+
+const DICE_FACES = ['i-lucide-dice-1', 'i-lucide-dice-2', 'i-lucide-dice-3', 'i-lucide-dice-4', 'i-lucide-dice-5', 'i-lucide-dice-6']
+const diceFace = ref(studioIcons.dice)
+const rolling = ref(false)
+
+// Only Lucide ships numbered faces; other packs spin their single die.
+watch(() => studioIcons.dice, (die) => {
+  if (!rolling.value) diceFace.value = die
+})
+
+// Keep in sync with the dice-roll keyframes: the stops are where the die hits
+// an edge, each impact flips the face.
+const ROLL_MS = 675
+const HIT_FRACTIONS = [0.064, 0.147, 0.255, 0.395, 0.578, 0.815]
+let rollTimers: Array<ReturnType<typeof setTimeout>> = []
+
+function randomFace() {
+  if (iconSet.value !== 'lucide') return studioIcons.dice
+  return DICE_FACES[Math.floor(Math.random() * DICE_FACES.length)]!
+}
+
+function clearRollTimers() {
+  rollTimers.forEach(timer => clearTimeout(timer))
+  rollTimers = []
+}
+
+async function rollDice() {
+  shuffle()
+  if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+    diceFace.value = randomFace()
+    return
+  }
+  // drop the class for a tick so a mid-roll re-click restarts the animation
+  clearRollTimers()
+  rolling.value = false
+  await nextTick()
+  rolling.value = true
+  rollTimers = HIT_FRACTIONS.map(fraction => setTimeout(() => (diceFace.value = randomFace()), ROLL_MS * fraction))
+  // safety net for environments that never fire animationend
+  rollTimers.push(setTimeout(onRollEnd, ROLL_MS + 400))
+}
+
+// The animation clock decides the end, a JS timer would race it and snap the
+// tumble back a few frames early.
+function onRollEnd(event?: AnimationEvent) {
+  if (event && !event.animationName.includes('dice-roll')) return
+  if (!rolling.value) return
+  clearRollTimers()
+  rolling.value = false
+  // no swap here: the face thrown on the last bounce IS the result
+}
+
+onUnmounted(clearRollTimers)
+</script>
+
+<template>
+  <UTooltip text="Random theme">
+    <UButton
+      :icon="diceFace"
+      color="neutral"
+      variant="outline"
+      :size="size"
+      aria-label="Random theme"
+      :class="rolling && 'dice-bumping'"
+      :ui="{ leadingIcon: rolling ? 'dice-rolling' : undefined }"
+      @click="rollDice"
+      @animationend="onRollEnd"
+    />
+  </UTooltip>
+</template>
+
+<style scoped>
+/* Impact stops mirror HIT_FRACTIONS; rotation ends on -540° (pips are
+   180°-symmetric, so the settled face reads upright). */
+@keyframes dice-roll {
+  0% { transform: translate(0px, 0px) rotate(0deg) scale(1); }
+  6.4% { transform: translate(-8px, 6px) rotate(-73deg) scale(0.88); }
+  7.9% { transform: translate(-8px, 6px) rotate(-73deg) scale(1); }
+  14.7% { transform: translate(7.2px, -5.6px) rotate(-149deg) scale(0.88); }
+  16.2% { transform: translate(7.2px, -5.6px) rotate(-149deg) scale(1); }
+  25.5% { transform: translate(-6px, -6.8px) rotate(-228deg) scale(0.88); }
+  27% { transform: translate(-6px, -6.8px) rotate(-228deg) scale(1); }
+  39.5% { transform: translate(6.8px, 4.8px) rotate(-310deg) scale(0.88); }
+  41% { transform: translate(6.8px, 4.8px) rotate(-310deg) scale(1); }
+  57.8% { transform: translate(-7.2px, 2.8px) rotate(-396deg) scale(0.88); }
+  59.3% { transform: translate(-7.2px, 2.8px) rotate(-396deg) scale(1); }
+  81.5% { transform: translate(5.6px, -6.4px) rotate(-485deg) scale(0.88); }
+  83% { transform: translate(5.6px, -6.4px) rotate(-485deg) scale(1); }
+  100% { transform: translate(0px, 0px) rotate(-540deg) scale(1); }
+}
+
+/* the container pops with every hit, fading as the die loses energy */
+@keyframes dice-bump {
+  0% { transform: scale(1); }
+  2.9% { transform: scale(1); }
+  6.4% { transform: scale(1.12); }
+  9.9% { transform: scale(1); }
+  11.2% { transform: scale(1); }
+  14.7% { transform: scale(1.096); }
+  18.2% { transform: scale(1); }
+  22% { transform: scale(1); }
+  25.5% { transform: scale(1.077); }
+  29% { transform: scale(1); }
+  36% { transform: scale(1); }
+  39.5% { transform: scale(1.061); }
+  43% { transform: scale(1); }
+  54.3% { transform: scale(1); }
+  57.8% { transform: scale(1.049); }
+  61.3% { transform: scale(1); }
+  78% { transform: scale(1); }
+  81.5% { transform: scale(1.039); }
+  85% { transform: scale(1); }
+  100% { transform: scale(1); }
+}
+
+/* the icon span renders inside UButton, scoped rules need :deep() */
+:deep(.dice-rolling) {
+  animation: dice-roll 675ms linear forwards;
+}
+
+.dice-bumping {
+  animation: dice-bump 675ms linear forwards;
+}
+</style>
diff --git a/docs/app/components/theme-studio/ThemeStudioTokenShades.vue b/docs/app/components/theme-studio/ThemeStudioTokenShades.vue
new file mode 100644
index 0000000000..76f438c600
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioTokenShades.vue
@@ -0,0 +1,45 @@
+<script setup lang="ts">
+import { TOKEN_GROUPS } from '../../utils/theme/engine'
+import type { ColorAlias, TokenGroup } from '../../utils/theme/engine'
+
+/**
+ * Per-mode shade rows for one ramp's semantic tokens. Shared by the Colors
+ * panel and the Style panel's Borders section, so a group can sit next to
+ * whichever control it belongs with.
+ */
+const props = defineProps<{
+  alias: ColorAlias
+  /** Restrict to these token groups; omit to show every group with tokens. */
+  groups?: TokenGroup[]
+}>()
+
+const { rampChip } = useThemeStudio()
+const { shadeLadder, sections } = useTokenShades(props.alias)
+
+const tokenGroups = TOKEN_GROUPS
+  .filter(group => !props.groups || props.groups.includes(group.key))
+  .map(group => ({ ...group, sections: sections.filter(section => section.group === group.key) }))
+  .filter(group => group.sections.length)
+</script>
+
+<template>
+  <div class="flex flex-col gap-2">
+    <!-- Every group keeps its name: a headerless section can't fold, and its
+         tokens would spill out flat wherever it's dropped. -->
+    <ThemeStudioSection
+      v-for="tokenGroup in tokenGroups"
+      :key="tokenGroup.key"
+      :label="tokenGroup.label"
+    >
+      <ThemeStudioShadeGroup
+        v-for="section in tokenGroup.sections"
+        :key="section.token"
+        :label="`${tokenGroup.label.replace(/ shades$/, '')} ${section.label.toLowerCase()}`"
+        separator
+        :sliders="section.sliders"
+        :chip="rampChip(section.ramp)"
+        :ladder="shadeLadder"
+      />
+    </ThemeStudioSection>
+  </div>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioToolbarField.vue b/docs/app/components/theme-studio/ThemeStudioToolbarField.vue
new file mode 100644
index 0000000000..c7aa6aa86e
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioToolbarField.vue
@@ -0,0 +1,17 @@
+<script setup lang="ts">
+/** A toolbar control: tooltipped, its label read out to assistive tech. */
+defineProps<{ label: string }>()
+
+// The bar is a fixed strip under the preview, so a visible label per control
+// would cost a row of height the preview wants. `text-xs` rides the root
+// class rather than `size="xs"`: the size prop is injected into every form
+// component inside, so the selects rendered here would shrink to xs while
+// the plain buttons beside them stayed md.
+const ui = { root: 'shrink-0 text-xs', label: 'hidden', container: 'mt-0' }
+</script>
+
+<template>
+  <UFormField :label="label" :ui="ui">
+    <slot :tooltip="label" />
+  </UFormField>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioToolbarPopover.vue b/docs/app/components/theme-studio/ThemeStudioToolbarPopover.vue
new file mode 100644
index 0000000000..6543d0e442
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioToolbarPopover.vue
@@ -0,0 +1,47 @@
+<script setup lang="ts">
+import { keepPanels } from '../../utils/theme/studio'
+/**
+ * A labelled toolbar button opening its panel. The trigger reports the value
+ * it holds, and turns primary when that value has drifted from the preset.
+ */
+defineProps<{
+  label: string
+  icon?: string
+  /** The trigger's text; omit for an icon-only button. */
+  value?: string
+  dirty?: boolean
+}>()
+
+const open = defineModel<boolean>('open', { default: false })
+
+const appConfig = useAppConfig()
+</script>
+
+<template>
+  <ThemeStudioToolbarField :label="label">
+    <UPopover v-model:open="open" :content="{ align: 'start', onInteractOutside: keepPanels }">
+      <!-- Reka binds a tooltip to its ONE child element, a popover root
+           renders nothing, so the tooltip has to sit on the button. -->
+      <UTooltip :text="label">
+        <UButton
+          :label="value"
+          :icon="icon"
+          :trailing-icon="appConfig.ui.icons.chevronDown"
+          :color="dirty ? 'primary' : 'neutral'"
+          variant="outline"
+          :class="value && 'w-38'"
+          :ui="{ label: 'flex-1 min-w-0 text-left truncate' }"
+          :aria-label="label"
+        >
+          <template v-if="!!$slots.leading" #leading>
+            <slot name="leading" />
+          </template>
+        </UButton>
+      </UTooltip>
+
+      <template #content>
+        <slot />
+      </template>
+    </UPopover>
+  </ThemeStudioToolbarField>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioViewA11y.vue b/docs/app/components/theme-studio/ThemeStudioViewA11y.vue
new file mode 100644
index 0000000000..384a328034
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioViewA11y.vue
@@ -0,0 +1,310 @@
+<script setup lang="ts">
+import type { ButtonProps } from '@nuxt/ui'
+import { blendColors, contrastRatio } from '../../utils/theme/engine'
+
+/**
+ * WCAG contrast matrix for the current theme, read from the live computed
+ * custom properties, the resolved ground truth.
+ */
+const FOREGROUNDS = [
+  { token: '--ui-text-highlighted', label: 'Highlighted', class: 'text-highlighted' },
+  { token: '--ui-text', label: 'Text', class: 'text-default' },
+  { token: '--ui-text-toned', label: 'Toned', class: 'text-toned' },
+  { token: '--ui-text-muted', label: 'Muted', class: 'text-muted' },
+  { token: '--ui-text-dimmed', label: 'Dimmed', class: 'text-dimmed' },
+  { token: '--ui-primary', label: 'Primary', class: 'text-primary' },
+  { token: '--ui-secondary', label: 'Secondary', class: 'text-secondary' },
+  { token: '--ui-success', label: 'Success', class: 'text-success' },
+  { token: '--ui-info', label: 'Info', class: 'text-info' },
+  { token: '--ui-warning', label: 'Warning', class: 'text-warning' },
+  { token: '--ui-error', label: 'Error', class: 'text-error' }
+]
+
+const BACKGROUNDS = [
+  { token: '--ui-bg', label: 'Default', class: 'bg-default' },
+  { token: '--ui-bg-muted', label: 'Muted', class: 'bg-muted' },
+  { token: '--ui-bg-elevated', label: 'Elevated', class: 'bg-elevated' },
+  { token: '--ui-bg-accented', label: 'Accented', class: 'bg-accented' },
+  { token: '--ui-bg-inverted', label: 'Inverted', class: 'bg-inverted' }
+]
+
+/** Solid surfaces (buttons, badges) render --ui-text-inverted on the alias. */
+const SOLIDS = FOREGROUNDS.slice(5)
+
+// Tinted variants measure the composited pixel (alias alpha over the page),
+// not the alias against a surface it never touches.
+const VARIANTS = ['solid', 'outline', 'soft', 'subtle', 'ghost', 'link'] as const
+
+const VARIANT_COLORS: Array<{ key: NonNullable<ButtonProps['color']>, label: string, icon: string }> = [
+  { key: 'primary', label: 'Primary', icon: 'i-lucide-rocket' },
+  { key: 'secondary', label: 'Secondary', icon: 'i-lucide-sparkles' },
+  { key: 'success', label: 'Success', icon: 'i-lucide-circle-check' },
+  { key: 'info', label: 'Info', icon: 'i-lucide-info' },
+  { key: 'warning', label: 'Warning', icon: 'i-lucide-triangle-alert' },
+  { key: 'error', label: 'Error', icon: 'i-lucide-circle-x' },
+  { key: 'neutral', label: 'Neutral', icon: 'i-lucide-settings' }
+]
+
+interface Cell {
+  fg: string
+  bg: string
+  ratio: number | null
+}
+
+const matrix = ref<Cell[][]>([])
+const solidRow = ref<Cell[]>([])
+const variantMatrix = ref<Cell[][]>([])
+
+function resolveToken(styles: CSSStyleDeclaration, token: string): string {
+  return styles.getPropertyValue(token).trim()
+}
+
+function compute() {
+  if (!import.meta.client) return
+  const styles = getComputedStyle(document.documentElement)
+
+  matrix.value = FOREGROUNDS.map(fg => BACKGROUNDS.map((bg) => {
+    const fgColor = resolveToken(styles, fg.token)
+    const bgColor = resolveToken(styles, bg.token)
+    return { fg: fgColor, bg: bgColor, ratio: contrastRatio(fgColor, bgColor) }
+  }))
+
+  const inverted = resolveToken(styles, '--ui-text-inverted')
+  solidRow.value = SOLIDS.map((solid) => {
+    const bgColor = resolveToken(styles, solid.token)
+    return { fg: inverted, bg: bgColor, ratio: contrastRatio(inverted, bgColor) }
+  })
+
+  const page = resolveToken(styles, '--ui-bg')
+  // Alpha of a token over the page background, `bg-primary/10` as a pixel.
+  const tint = (token: string, alpha: number) => blendColors(resolveToken(styles, token), page, alpha) ?? ''
+
+  variantMatrix.value = VARIANT_COLORS.map(({ key }) => {
+    const specs = key === 'neutral'
+      ? neutralSpecs(styles, page, inverted)
+      : semanticSpecs(styles, `--ui-${key}`, page, inverted, tint)
+
+    return specs.map(spec => ({ ...spec, ratio: contrastRatio(spec.fg, spec.bg) }))
+  })
+}
+
+/** Per-variant fg/bg for a semantic alias, in VARIANTS order. */
+function semanticSpecs(
+  styles: CSSStyleDeclaration,
+  token: string,
+  page: string,
+  inverted: string,
+  tint: (token: string, alpha: number) => string
+): Array<Omit<Cell, 'ratio'>> {
+  const color = resolveToken(styles, token)
+  const tinted = tint(token, 0.1)
+  return [
+    { fg: inverted, bg: color },
+    { fg: color, bg: page },
+    { fg: color, bg: tinted },
+    { fg: color, bg: tinted },
+    { fg: color, bg: page },
+    { fg: color, bg: page }
+  ]
+}
+
+/** Neutral resolves to surface/text tokens rather than a semantic alias. */
+function neutralSpecs(styles: CSSStyleDeclaration, page: string, inverted: string): Array<Omit<Cell, 'ratio'>> {
+  const text = resolveToken(styles, '--ui-text')
+  const elevated = resolveToken(styles, '--ui-bg-elevated')
+  return [
+    { fg: inverted, bg: resolveToken(styles, '--ui-bg-inverted') },
+    { fg: text, bg: page },
+    { fg: text, bg: elevated },
+    { fg: text, bg: elevated },
+    { fg: text, bg: page },
+    { fg: resolveToken(styles, '--ui-text-muted'), bg: page }
+  ]
+}
+
+// The theme applies through <style> tags useHead swaps asynchronously,
+// recompute a beat after any state that feeds them changes.
+const colorMode = useColorMode()
+const appConfig = useAppConfig()
+// the owning composable's refs, never re-seed these channels here
+const { cssVariablesData, customColorsData } = useTheme()
+
+// useHead swaps the style tags asynchronously: wait a tick for the vnodes,
+// then two frames so the new sheets are applied before reading computed
+// styles, deterministic, unlike a wall-clock delay.
+let pending = 0
+let queued = false
+function scheduleCompute() {
+  cancelAnimationFrame(pending)
+  // one queued tick at a time, curve drags would otherwise stack nextTick
+  // callbacks, each spawning its own rAF chain
+  if (queued) return
+  queued = true
+  nextTick(() => {
+    queued = false
+    pending = requestAnimationFrame(() => {
+      pending = requestAnimationFrame(compute)
+    })
+  })
+}
+
+watch([() => colorMode.value, () => ({ ...appConfig.ui.colors }), cssVariablesData, customColorsData], scheduleCompute)
+
+// The theme lands as <style> tags useHead swaps, and the view remounts on an
+// icon-pack change (the preview is keyed on it), so it can mount BEFORE the
+// sheet it should read. Watching the head covers every path into a new theme,
+// whichever order the two arrive in.
+let observer: MutationObserver | undefined
+onMounted(() => {
+  scheduleCompute()
+  observer = new MutationObserver(scheduleCompute)
+  observer.observe(document.head, { childList: true, subtree: true, characterData: true })
+})
+
+onUnmounted(() => {
+  observer?.disconnect()
+  cancelAnimationFrame(pending)
+})
+
+function level(ratio: number | null): { label: string, color: 'success' | 'warning' | 'error' | 'neutral' } {
+  // Unparseable color, signal unknown rather than a fabricated pass/fail.
+  if (ratio === null) return { label: 'Unknown', color: 'neutral' }
+  if (ratio >= 7) return { label: 'AAA', color: 'success' }
+  if (ratio >= 4.5) return { label: 'AA', color: 'success' }
+  if (ratio >= 3) return { label: 'AA18', color: 'warning' }
+  return { label: 'Fail', color: 'error' }
+}
+
+/** Ratio display: numeric to 1 decimal, or an em dash when unmeasurable. */
+function formatRatio(ratio: number | null): string {
+  return ratio === null ? '-' : ratio.toFixed(1)
+}
+</script>
+
+<template>
+  <div class="h-full overflow-y-auto p-4 sm:p-6">
+    <div class="max-w-4xl mx-auto flex flex-col gap-8">
+      <div>
+        <h2 class="text-sm font-semibold text-highlighted mb-1">
+          Text on surfaces
+        </h2>
+        <p class="text-xs text-muted mb-4">
+          WCAG 2.x contrast for every text role against every surface token, resolved from the live theme.
+          AA needs 4.5:1 (3:1 for large text), AAA needs 7:1.
+        </p>
+
+        <div class="overflow-x-auto">
+          <table class="w-full text-xs">
+            <thead>
+              <tr>
+                <th class="text-left font-medium text-muted p-2" />
+                <th v-for="bg in BACKGROUNDS" :key="bg.token" class="text-left font-medium text-muted p-2">
+                  {{ bg.label }}
+                </th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr v-for="(fg, row) in FOREGROUNDS" :key="fg.token">
+                <th class="text-left font-medium text-muted p-2 whitespace-nowrap">
+                  {{ fg.label }}
+                </th>
+                <td v-for="(bg, col) in BACKGROUNDS" :key="bg.token" class="p-1">
+                  <div
+                    class="rounded-md px-2.5 py-2 flex items-center justify-between gap-2 ring ring-default"
+                    :class="[bg.class, fg.class]"
+                  >
+                    <span class="font-semibold">Aa</span>
+                    <span class="flex items-center gap-1.5">
+                      <span class="tabular-nums font-mono opacity-80">
+                        {{ formatRatio(matrix[row]?.[col]?.ratio ?? null) }}
+                      </span>
+                      <UBadge :label="level(matrix[row]?.[col]?.ratio ?? null).label" :color="level(matrix[row]?.[col]?.ratio ?? null).color" variant="solid" size="sm" />
+                    </span>
+                  </div>
+                </td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div>
+        <h2 class="text-sm font-semibold text-highlighted mb-1">
+          Inverted text on solid surfaces
+        </h2>
+        <p class="text-xs text-muted mb-4">
+          What solid buttons and badges render: the inverted text token on each semantic color.
+        </p>
+
+        <div class="grid grid-cols-2 sm:grid-cols-3 xl:grid-cols-6 gap-2">
+          <div
+            v-for="(cell, index) in solidRow"
+            :key="SOLIDS[index]!.token"
+            class="rounded-md px-2.5 py-3 flex flex-col gap-1.5 ring ring-default"
+            :style="{ backgroundColor: cell.bg }"
+          >
+            <span class="text-xs font-semibold" :style="{ color: cell.fg }">{{ SOLIDS[index]!.label }}</span>
+            <span class="flex items-center gap-1.5">
+              <span class="text-xs tabular-nums font-mono opacity-80" :style="{ color: cell.fg }">
+                {{ formatRatio(cell.ratio) }}
+              </span>
+              <UBadge :label="level(cell.ratio).label" :color="level(cell.ratio).color" variant="solid" size="sm" />
+            </span>
+          </div>
+        </div>
+      </div>
+
+      <div>
+        <h2 class="text-sm font-semibold text-highlighted mb-1">
+          Button &amp; badge variants
+        </h2>
+        <p class="text-xs text-muted mb-4">
+          Every color × variant as it paints on the page background, tinted variants are measured against the
+          composited pixel, not the raw alias.
+        </p>
+
+        <div class="overflow-x-auto">
+          <table class="w-full text-xs">
+            <thead>
+              <tr>
+                <th class="text-left font-medium text-muted p-2" />
+                <th v-for="variant in VARIANTS" :key="variant" class="text-left font-medium text-muted p-2 capitalize">
+                  {{ variant }}
+                </th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr v-for="(color, row) in VARIANT_COLORS" :key="color.key">
+                <th class="text-left font-medium text-muted p-2 whitespace-nowrap">
+                  {{ color.label }}
+                </th>
+                <td v-for="(variant, col) in VARIANTS" :key="variant" class="p-1 align-top">
+                  <UButton
+                    v-if="variantMatrix[row]?.[col]"
+                    as="span"
+                    :color="color.key"
+                    :variant="variant"
+                    :icon="color.icon"
+                    block
+                    :label="formatRatio(variantMatrix[row][col].ratio)"
+                    size="sm"
+                    :ui="{ label: 'font-mono tabular-nums' }"
+                  >
+                    <template #trailing>
+                      <UBadge
+                        :label="level(variantMatrix[row][col].ratio).label"
+                        :color="level(variantMatrix[row][col].ratio).color"
+                        variant="solid"
+                        size="sm"
+                      />
+                    </template>
+                  </UButton>
+                </td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioViewChangelog.vue b/docs/app/components/theme-studio/ThemeStudioViewChangelog.vue
new file mode 100644
index 0000000000..82955462b9
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioViewChangelog.vue
@@ -0,0 +1,276 @@
+<script setup lang="ts">
+// Replicates the official Nuxt UI Changelog template (nuxt-ui-templates/changelog)
+// in a single self-contained preview: app.vue's split layout with the sticky
+// intro panel + SkyBg on the left, and pages/index.vue's UChangelogVersions
+// feed on the right. Release notes are inlined since the template fetches them
+// from GitHub and renders them with Comark, neither of which is available here.
+
+const extra = useStudioExtraIcons()
+
+const introLinks = [{
+  label: 'Documentation',
+  icon: extra.bookOpen,
+  variant: 'ghost' as const,
+  size: 'md' as const
+}, {
+  label: 'GitHub',
+  icon: extra.github,
+  variant: 'ghost' as const,
+  size: 'md' as const
+}]
+
+// Invented releases standing in for the template's GitHub release notes.
+interface Release {
+  tag: string
+  title: string
+  date: string
+  intro: string
+  sections: {
+    title: string
+    items: { text: string, code?: string }[]
+  }[]
+  contributors: string[]
+}
+
+const versions: Release[] = [{
+  tag: 'v4.2.0',
+  title: 'v4.2.0',
+  date: '2026-06-18T10:00:00Z',
+  intro: 'This release focuses on data display: a brand new component, smarter tables and a batch of theme refinements across the board.',
+  sections: [{
+    title: 'Features',
+    items: [
+      { code: 'ChangelogVersions', text: 'new component to compose release notes with sticky version indicators' },
+      { code: 'Table', text: 'add column pinning and row expansion' },
+      { code: 'ColorPicker', text: 'support custom swatch sizes' },
+      { code: 'Slider', text: 'expose a slot to render content next to the value' }
+    ]
+  }, {
+    title: 'Bug fixes',
+    items: [
+      { code: 'Modal', text: 'prevent overlay flicker when nesting inside a drawer' },
+      { code: 'Carousel', text: 'respect reduced motion preferences during autoplay' }
+    ]
+  }],
+  contributors: ['benjamincanac', 'romhml', 'sandros94', 'hywax']
+}, {
+  tag: 'v4.1.0',
+  title: 'v4.1.0',
+  date: '2026-05-06T09:30:00Z',
+  intro: 'A quality-of-life release: better forms, better keyboard navigation and a handful of long-requested props.',
+  sections: [{
+    title: 'Features',
+    items: [
+      { code: 'Form', text: 'nested field support with dot notation paths' },
+      { code: 'CommandPalette', text: 'new prop to render items lazily in large lists' },
+      { code: 'Calendar', text: 'allow custom day cells through a slot' }
+    ]
+  }, {
+    title: 'Bug fixes',
+    items: [
+      { code: 'ContentSearch', text: 'keep focus within the panel when tabbing from the search input' },
+      { code: 'Input', text: 'fix RTL alignment of trailing icons' },
+      { code: 'Toast', text: 'avoid duplicate announcements of titles by screen readers' }
+    ]
+  }],
+  contributors: ['benjamincanac', 'noook', 'genu']
+}, {
+  tag: 'v4.0.1',
+  title: 'v4.0.1',
+  date: '2026-04-02T16:15:00Z',
+  intro: 'A small patch following the v4 launch, addressing the most reported issues from the first week.',
+  sections: [{
+    title: 'Bug fixes',
+    items: [
+      { text: 'Restore auto-import of prose components in docs projects' },
+      { code: 'Skeleton', text: 'fix hydration mismatch when used with SSR color mode' },
+      { code: 'Button', text: 'correct padding of the compact size' }
+    ]
+  }],
+  contributors: ['benjamincanac', 'danielroe']
+}, {
+  tag: 'v4.0.0',
+  title: 'v4.0.0',
+  date: '2026-03-24T14:00:00Z',
+  intro: 'Nuxt UI v4 unifies Nuxt UI and Nuxt UI Pro into a single free and open source library: 110+ components, Tailwind CSS v4, and a brand new theming system built on design tokens.',
+  sections: [{
+    title: 'Highlights',
+    items: [
+      { text: 'All Pro components are now free and open source: dashboard, page sections, chat and more' },
+      { text: 'Semantic color aliases with light and dark values generated from your palette' },
+      { code: 'ui', text: 'prop enables per-slot overrides on the rewritten Tailwind Variants theming' },
+      { text: 'First-class Vue support without Nuxt through the dedicated Vite plugin' }
+    ]
+  }, {
+    title: 'Breaking changes',
+    items: [
+      { code: 'Notification', text: 'renamed to Toast with a unified API' },
+      { text: 'Dropped Tailwind CSS v3 support, the config file is replaced by CSS-first configuration' }
+    ]
+  }],
+  contributors: ['benjamincanac', 'romhml', 'atinux', 'smarroufin', 'noook']
+}]
+
+// Inline replica of the template's SkyBg component: twinkling primary stars
+// scattered across the sticky intro panel.
+interface Star {
+  x: number
+  y: number
+  size: number
+  delay: number
+}
+
+const stars = ref<Star[]>([])
+
+onMounted(() => {
+  stars.value = Array.from({ length: 50 }, () => ({
+    x: Math.floor(Math.random() * 100),
+    y: Math.floor(Math.random() * 100),
+    size: Math.random() * 2 + 1,
+    delay: Math.random() * 5
+  }))
+})
+</script>
+
+<template>
+  <!-- The pane is the scroll container; the intro panel sticks to it on xl. -->
+  <div class="h-full overflow-y-auto bg-default">
+    <div class="min-h-full xl:grid xl:grid-cols-2">
+      <UPageSection
+        title="Changelog"
+        description="Display GitHub release notes as a beautiful changelog for any repository with this Nuxt UI template."
+        orientation="vertical"
+        :links="introLinks"
+        :ui="{
+          root: 'border-b border-default xl:border-b-0 xl:sticky xl:top-0 xl:h-svh overflow-hidden',
+          container: 'h-full items-center justify-center',
+          wrapper: 'flex flex-col',
+          headline: 'mb-6',
+          title: 'text-left text-4xl',
+          description: 'text-left max-w-lg',
+          links: 'gap-1 justify-start -ms-2.5'
+        }"
+      >
+        <template #top>
+          <!-- Template's SkyBg: twinkling primary stars. -->
+          <div class="absolute inset-0 pointer-events-none z-[-1] overflow-hidden">
+            <div
+              v-for="(star, index) in stars"
+              :key="index"
+              class="star absolute rounded-full bg-primary"
+              :style="{
+                'left': `${star.x}%`,
+                'top': `${star.y}%`,
+                'width': `${star.size}px`,
+                'height': `${star.size}px`,
+                'transform': 'translate(-50%, -50%)',
+                '--twinkle-delay': `${star.delay}s`
+              }"
+            />
+          </div>
+
+          <div class="absolute -right-1/2 z-[-1] rounded-full bg-primary blur-[300px] size-60 sm:size-100 transform -translate-y-1/2 top-1/2" />
+        </template>
+
+        <template #headline>
+          <!-- Stand-in for the template's AppLogo wordmark. -->
+          <div class="flex items-center gap-1.5 text-highlighted">
+            <UIcon name="i-simple-icons-nuxt" class="size-6 text-primary shrink-0" />
+            <span class="text-xl font-bold">Nuxt UI</span>
+          </div>
+        </template>
+
+        <template #default />
+      </UPageSection>
+
+      <section class="relative px-4 sm:px-6 xl:px-0 xl:-ms-30 xl:flex-1">
+        <UButton
+          icon="i-lucide-sun-moon"
+          aria-label="Color mode"
+          color="neutral"
+          variant="ghost"
+          class="absolute top-4 right-4 z-10"
+        />
+
+        <UChangelogVersions
+          as="main"
+          :indicator-motion="false"
+          :ui="{
+            root: 'py-16 sm:py-24 lg:py-32',
+            indicator: 'inset-y-0'
+          }"
+        >
+          <UChangelogVersion
+            v-for="version in versions"
+            :key="version.tag"
+            :title="version.title"
+            :date="version.date"
+            :ui="{
+              root: 'flex items-start',
+              container: 'max-w-xl min-w-0',
+              header: 'border-b border-default pb-4',
+              title: 'text-3xl',
+              date: 'text-xs/9 text-highlighted font-mono',
+              indicator: 'sticky top-0 pt-16 -mt-16 sm:pt-24 sm:-mt-24 lg:pt-32 lg:-mt-32'
+            }"
+          >
+            <template #body>
+              <!-- The template renders release markdown with Comark; this
+              preview inlines the notes as plain prose markup instead. -->
+              <div class="text-base text-muted space-y-6">
+                <p>{{ version.intro }}</p>
+
+                <div v-for="section in version.sections" :key="section.title" class="space-y-3">
+                  <h3 class="text-lg font-semibold text-highlighted">
+                    {{ section.title }}
+                  </h3>
+
+                  <ul class="list-disc ps-5 space-y-1.5 marker:text-dimmed">
+                    <li v-for="(item, index) in section.items" :key="index" class="wrap-break-word">
+                      <template v-if="item.code">
+                        <code class="px-1.5 py-0.5 font-mono text-sm font-medium rounded-md bg-elevated text-highlighted border border-default">{{ item.code }}</code>{{ ' ' }}
+                      </template>{{ item.text }}
+                    </li>
+                  </ul>
+                </div>
+
+                <div class="space-y-3">
+                  <h3 class="text-lg font-semibold text-highlighted">
+                    Contributors
+                  </h3>
+
+                  <UAvatarGroup size="md" :max="5">
+                    <UAvatar
+                      v-for="contributor in version.contributors"
+                      :key="contributor"
+                      :src="`https://github.com/${contributor}.png`"
+                      :alt="contributor"
+                    />
+                  </UAvatarGroup>
+                </div>
+              </div>
+            </template>
+          </UChangelogVersion>
+        </UChangelogVersions>
+      </section>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.star {
+  animation: changelog-twinkle 2s ease-in-out infinite;
+  animation-delay: var(--twinkle-delay);
+  will-change: opacity;
+}
+
+@keyframes changelog-twinkle {
+  0%, 100% {
+    opacity: 0.2;
+  }
+
+  50% {
+    opacity: 1;
+  }
+}
+</style>
diff --git a/docs/app/components/theme-studio/ThemeStudioViewChat.vue b/docs/app/components/theme-studio/ThemeStudioViewChat.vue
new file mode 100644
index 0000000000..5bf5ce9dae
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioViewChat.vue
@@ -0,0 +1,139 @@
+<script setup lang="ts">
+import type { UIMessage } from 'ai'
+import type { NavigationMenuItem } from '@nuxt/ui'
+
+const appConfig = useAppConfig()
+const extra = useStudioExtraIcons()
+
+const input = ref('')
+
+const menuItems: NavigationMenuItem[] = [
+  { label: 'New chat', icon: appConfig.ui.icons.plus },
+  { label: 'Search', icon: appConfig.ui.icons.search }
+]
+
+const historyItems: NavigationMenuItem[] = [
+  { label: 'Today', type: 'label' },
+  { label: 'Building a dashboard with Nuxt UI', active: true },
+  { label: 'Theming buttons and badges' },
+  { label: 'Yesterday', type: 'label' },
+  { label: 'Form validation with UForm' },
+  { label: 'Sidebar layout questions' },
+  { label: 'Previous 7 days', type: 'label' },
+  { label: 'Migrating an app to v4' },
+  { label: 'Dark mode color tokens' },
+  { label: 'Table sorting and pagination' }
+]
+
+const messages: UIMessage[] = [{
+  id: '1',
+  role: 'user',
+  parts: [{ type: 'text', text: 'I want to build a dashboard with Nuxt UI. Where should I start?' }]
+}, {
+  id: '2',
+  role: 'assistant',
+  parts: [{ type: 'text', text: 'Great choice! Start with UDashboardGroup as the root layout, then add a UDashboardSidebar for navigation and a UDashboardPanel for each page. The sidebar is collapsible and resizable out of the box, so you get a polished shell before writing any custom code.' }]
+}, {
+  id: '3',
+  role: 'user',
+  parts: [{ type: 'text', text: 'Nice. And how do I make it match my brand colors?' }]
+}, {
+  id: '4',
+  role: 'assistant',
+  parts: [{ type: 'text', text: 'Define your palette once in @theme and map it to the primary and neutral aliases in app.config.ts. Every component reads from those semantic tokens, so buttons, badges, inputs and even this chat pick up your brand automatically, exactly what this preview is showing you right now.' }]
+}, {
+  id: '5',
+  role: 'user',
+  parts: [{ type: 'text', text: 'Perfect, that saves me a ton of CSS. Ship it!' }]
+}]
+</script>
+
+<template>
+  <div class="h-full flex bg-default overflow-hidden">
+    <aside class="hidden md:flex w-56 shrink-0 flex-col gap-2 border-e border-default bg-elevated/25 p-3 min-h-0">
+      <div class="flex items-center gap-1.5 px-1.5 py-1">
+        <UIcon :name="extra.messageCircle" class="size-5 text-primary shrink-0" />
+        <span class="text-lg font-bold text-highlighted">Chat</span>
+      </div>
+
+      <UNavigationMenu :items="menuItems" orientation="vertical" />
+
+      <div class="flex-1 min-h-0 overflow-y-auto">
+        <UNavigationMenu :items="historyItems" orientation="vertical" :ui="{ link: 'overflow-hidden' }" />
+      </div>
+
+      <UButton
+        label="Anna Cooper"
+        :avatar="{ alt: 'Anna Cooper' }"
+        :trailing-icon="extra.sort"
+        color="neutral"
+        variant="ghost"
+        class="w-full"
+        :ui="{ trailingIcon: 'ms-auto text-dimmed' }"
+      />
+    </aside>
+
+    <div class="flex-1 flex flex-col min-w-0 min-h-0">
+      <div class="h-12 shrink-0 flex items-center justify-between gap-2 border-b border-default px-4">
+        <p class="text-sm font-medium text-highlighted truncate">
+          Building a dashboard with Nuxt UI
+        </p>
+
+        <div class="flex items-center gap-1">
+          <UButton
+            label="Private"
+            :icon="extra.lock"
+            :trailing-icon="appConfig.ui.icons.chevronDown"
+            color="neutral"
+            variant="ghost"
+            size="sm"
+          />
+          <UButton
+            :icon="extra.share"
+            color="neutral"
+            variant="ghost"
+            size="sm"
+            square
+            aria-label="Share chat"
+          />
+        </div>
+      </div>
+
+      <div class="flex-1 min-h-0 overflow-y-auto">
+        <UChatMessages
+          :messages="messages"
+          status="ready"
+          :should-scroll-to-bottom="false"
+          :auto-scroll="false"
+          class="p-4 sm:p-6"
+        />
+      </div>
+
+      <div class="shrink-0 px-4 pb-4 sm:px-6">
+        <UChatPrompt v-model="input" placeholder="Ask anything about Nuxt UI...">
+          <template #footer>
+            <div class="flex items-center gap-1">
+              <UButton
+                :icon="extra.paperclip"
+                color="neutral"
+                variant="ghost"
+                size="sm"
+                square
+                aria-label="Attach file"
+              />
+              <UButton
+                label="gpt-4o"
+                :trailing-icon="appConfig.ui.icons.chevronDown"
+                color="neutral"
+                variant="ghost"
+                size="sm"
+              />
+            </div>
+
+            <UChatPromptSubmit status="ready" size="sm" />
+          </template>
+        </UChatPrompt>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioViewDashboard.vue b/docs/app/components/theme-studio/ThemeStudioViewDashboard.vue
new file mode 100644
index 0000000000..1317c79ee0
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioViewDashboard.vue
@@ -0,0 +1,913 @@
+<script setup lang="ts">
+import { h, resolveComponent } from 'vue'
+import type { DropdownMenuItem, NavigationMenuItem, TableColumn } from '@nuxt/ui'
+
+const UAvatar = resolveComponent('UAvatar')
+const UBadge = resolveComponent('UBadge')
+const UButton = resolveComponent('UButton')
+const UCheckbox = resolveComponent('UCheckbox')
+const UDropdownMenu = resolveComponent('UDropdownMenu')
+
+const appConfig = useAppConfig()
+const extra = useStudioExtraIcons()
+
+type Page = 'home' | 'inbox' | 'customers' | 'settings'
+const page = ref<Page>('home')
+const settingsSection = ref<'general' | 'notifications'>('general')
+
+const teams = [
+  { label: 'Nuxt', avatar: { src: 'https://github.com/nuxt.png', alt: 'Nuxt' } },
+  { label: 'NuxtHub', avatar: { src: 'https://github.com/nuxt-hub.png', alt: 'NuxtHub' } },
+  { label: 'NuxtLabs', avatar: { src: 'https://github.com/nuxtlabs.png', alt: 'NuxtLabs' } }
+]
+const selectedTeam = ref(teams[0]!)
+
+const teamItems = computed<DropdownMenuItem[][]>(() => [
+  teams.map(team => ({ ...team, onSelect: () => { selectedTeam.value = team } })),
+  [
+    { label: 'Create team', icon: appConfig.ui.icons.plus },
+    { label: 'Manage teams', icon: extra.settings }
+  ]
+])
+
+const links = computed<NavigationMenuItem[][]>(() => [[{
+  label: 'Home',
+  icon: extra.home,
+  active: page.value === 'home',
+  onSelect: () => { page.value = 'home' }
+}, {
+  label: 'Inbox',
+  icon: extra.inbox,
+  badge: String(unreadCount),
+  active: page.value === 'inbox',
+  onSelect: () => { page.value = 'inbox' }
+}, {
+  label: 'Customers',
+  icon: extra.users,
+  active: page.value === 'customers',
+  onSelect: () => { page.value = 'customers' }
+}, {
+  label: 'Settings',
+  icon: extra.settings,
+  defaultOpen: true,
+  type: 'trigger',
+  active: page.value === 'settings',
+  children: [{
+    label: 'General',
+    active: page.value === 'settings' && settingsSection.value === 'general',
+    onSelect: () => {
+      page.value = 'settings'
+      settingsSection.value = 'general'
+    }
+  }, {
+    label: 'Notifications',
+    active: page.value === 'settings' && settingsSection.value === 'notifications',
+    onSelect: () => {
+      page.value = 'settings'
+      settingsSection.value = 'notifications'
+    }
+  }]
+}], [{
+  label: 'Feedback',
+  icon: extra.messageCircle
+}, {
+  label: 'Help & Support',
+  icon: appConfig.ui.icons.info
+}]])
+
+const user = {
+  name: 'Benjamin Canac',
+  avatar: { src: 'https://github.com/benjamincanac.png', alt: 'Benjamin Canac' }
+}
+
+const userItems: DropdownMenuItem[][] = [[{
+  type: 'label',
+  label: user.name,
+  avatar: user.avatar
+}], [
+  { label: 'Profile', icon: extra.user },
+  { label: 'Billing', icon: extra.creditCard },
+  { label: 'Settings', icon: extra.settings }
+], [
+  { label: 'Log out', icon: extra.logout }
+]]
+
+const newItems: DropdownMenuItem[][] = [[
+  { label: 'New mail', icon: extra.send },
+  { label: 'New customer', icon: extra.userPlus }
+]]
+
+const periodItems = ['Daily', 'Weekly', 'Monthly']
+const period = ref('Daily')
+
+const stats = [
+  { title: 'Customers', icon: extra.users, value: '892', variation: 14 },
+  { title: 'Conversions', icon: extra.chart, value: '1,436', variation: 8 },
+  { title: 'Revenue', icon: extra.dollar, value: '$312,540', variation: 23 },
+  { title: 'Orders', icon: extra.cart, value: '254', variation: -5 }
+]
+
+const revenue = [6200, 7400, 6800, 9100, 8600, 10400, 9800, 11900, 11200, 13000, 12400, 14100, 13600, 15200]
+const revenueMin = Math.min(...revenue)
+const revenueMax = Math.max(...revenue)
+const chartPoints = revenue
+  .map((value, index) => `${(index * (400 / (revenue.length - 1))).toFixed(1)},${(110 - ((value - revenueMin) / (revenueMax - revenueMin)) * 100).toFixed(1)}`)
+  .join(' ')
+const chartArea = `0,120 ${chartPoints} 400,120`
+const chartTicks = ['22 Jun', '26 Jun', '30 Jun', '3 Jul', '6 Jul']
+const revenueTotal = new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+  maximumFractionDigits: 0
+}).format(revenue.reduce((acc, amount) => acc + amount, 0))
+
+type Sale = {
+  id: string
+  date: string
+  status: 'paid' | 'failed' | 'refunded'
+  email: string
+  amount: number
+}
+
+const sales: Sale[] = [
+  { id: '4600', date: 'Jul 6, 14:32', status: 'paid', email: 'james.anderson@example.com', amount: 594 },
+  { id: '4599', date: 'Jul 6, 11:05', status: 'failed', email: 'mia.white@example.com', amount: 276 },
+  { id: '4598', date: 'Jul 5, 22:47', status: 'refunded', email: 'william.brown@example.com', amount: 315 },
+  { id: '4597', date: 'Jul 5, 18:20', status: 'paid', email: 'emma.davis@example.com', amount: 529 },
+  { id: '4596', date: 'Jul 5, 09:12', status: 'paid', email: 'ethan.harris@example.com', amount: 639 }
+]
+
+const salesColumns: TableColumn<Sale>[] = [{
+  accessorKey: 'id',
+  header: 'ID',
+  cell: ({ row }) => `#${row.getValue('id')}`
+}, {
+  accessorKey: 'date',
+  header: 'Date'
+}, {
+  accessorKey: 'status',
+  header: 'Status',
+  cell: ({ row }) => {
+    const color = ({
+      paid: 'success' as const,
+      failed: 'error' as const,
+      refunded: 'neutral' as const
+    })[row.getValue('status') as string]
+
+    return h(UBadge, { class: 'capitalize', color }, () => row.getValue('status'))
+  }
+}, {
+  accessorKey: 'email',
+  header: 'Email'
+}, {
+  accessorKey: 'amount',
+  header: 'Amount',
+  meta: {
+    class: {
+      th: 'text-right',
+      td: 'text-right font-medium'
+    }
+  },
+  cell: ({ row }) => {
+    return new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: 'EUR'
+    }).format(Number.parseFloat(row.getValue('amount')))
+  }
+}]
+
+// Inbox, mirrors app/pages/inbox.vue + InboxList/InboxMail from the template,
+// with dates pre-formatted as strings instead of pulling in date-fns.
+type Mail = {
+  id: number
+  unread?: boolean
+  from: { name: string, email: string, avatar: { src: string, alt: string } }
+  subject: string
+  date: string
+  datetime: string
+  body: string
+}
+
+const mails: Mail[] = [{
+  id: 1,
+  unread: true,
+  from: { name: 'Alex Smith', email: 'alex.smith@example.com', avatar: { src: 'https://github.com/nuxt.png', alt: 'Alex Smith' } },
+  subject: 'Meeting Schedule: Project Update',
+  date: '14:32',
+  datetime: '10 Jul 14:32',
+  body: 'Hi there,\n\nJust a quick reminder that we have a meeting scheduled for tomorrow at 10 AM to discuss the latest project updates. Please come prepared with your progress reports.\n\nBest regards,\nAlex'
+}, {
+  id: 2,
+  unread: true,
+  from: { name: 'Jordan Brown', email: 'jordan.brown@example.com', avatar: { src: 'https://github.com/nuxtlabs.png', alt: 'Jordan Brown' } },
+  subject: 'Urgent: Server Maintenance Tonight',
+  date: '11:05',
+  datetime: '10 Jul 11:05',
+  body: 'Attention team,\n\nWe will be conducting server maintenance tonight from 11 PM to 2 AM. During this period, all services will be temporarily unavailable. We apologize for the inconvenience.\n\nIT Department'
+}, {
+  id: 3,
+  from: { name: 'Taylor Green', email: 'taylor.green@example.com', avatar: { src: 'https://github.com/nuxt-hub.png', alt: 'Taylor Green' } },
+  subject: 'Feedback Request: New Design Mockups',
+  date: '09 Jul',
+  datetime: '09 Jul 16:20',
+  body: 'Hello,\n\nWe value your opinion! Could you please take a moment to review the attached design mockups for the upcoming dashboard refresh? Your feedback would be greatly appreciated.\n\nThank you,\nTaylor'
+}, {
+  id: 4,
+  unread: true,
+  from: { name: 'Morgan White', email: 'morgan.white@example.com', avatar: { src: 'https://github.com/vitejs.png', alt: 'Morgan White' } },
+  subject: 'Invitation: Annual Company Retreat',
+  date: '08 Jul',
+  datetime: '08 Jul 10:12',
+  body: 'Dear colleague,\n\nYou are cordially invited to our annual company retreat on August 15th. It will be a great opportunity to unwind and connect with your peers outside the office.\n\nRSVP by July 25th.\n\nHR Team'
+}, {
+  id: 5,
+  from: { name: 'Casey Gray', email: 'casey.gray@example.com', avatar: { src: 'https://github.com/vuejs.png', alt: 'Casey Gray' } },
+  subject: 'Reminder: Submit Your Timesheets',
+  date: '07 Jul',
+  datetime: '07 Jul 08:45',
+  body: 'Hi all,\n\nThis is a friendly reminder to submit your timesheets by the end of the day Friday. Timely submission helps us process payroll without delays.\n\nThanks,\nCasey'
+}]
+
+const unreadCount = mails.filter(mail => mail.unread).length
+
+const mailTabItems = [{ label: 'All', value: 'all' }, { label: 'Unread', value: 'unread' }]
+const selectedMailTab = ref('all')
+
+const filteredMails = computed(() => {
+  return selectedMailTab.value === 'unread' ? mails.filter(mail => !!mail.unread) : mails
+})
+
+const selectedMail = ref<Mail | null>(mails[0]!)
+
+// Reset selected mail if it's not in the filtered mails
+watch(filteredMails, () => {
+  if (!filteredMails.value.find(mail => mail.id === selectedMail.value?.id)) {
+    selectedMail.value = filteredMails.value[0] ?? null
+  }
+})
+
+const mailDropdownItems: DropdownMenuItem[][] = [[
+  { label: 'Mark as unread', icon: appConfig.ui.icons.success },
+  { label: 'Mark as important', icon: appConfig.ui.icons.warning }
+], [
+  { label: 'Star thread', icon: appConfig.ui.icons.star }
+]]
+
+const reply = ref('')
+
+// Customers, mirrors app/pages/customers.vue from the template.
+type Customer = {
+  id: number
+  name: string
+  username: string
+  email: string
+  location: string
+  status: 'subscribed' | 'unsubscribed' | 'bounced'
+  avatar: { src: string, alt: string }
+}
+
+const customers: Customer[] = [
+  { id: 1, name: 'Alex Smith', username: 'alexsmith', email: 'alex.smith@example.com', location: 'New York, USA', status: 'subscribed', avatar: { src: 'https://github.com/nuxt.png', alt: 'Alex Smith' } },
+  { id: 2, name: 'Jordan Brown', username: 'jordanbrown', email: 'jordan.brown@example.com', location: 'London, UK', status: 'unsubscribed', avatar: { src: 'https://github.com/nuxtlabs.png', alt: 'Jordan Brown' } },
+  { id: 3, name: 'Taylor Green', username: 'taylorgreen', email: 'taylor.green@example.com', location: 'Paris, France', status: 'bounced', avatar: { src: 'https://github.com/nuxt-hub.png', alt: 'Taylor Green' } },
+  { id: 4, name: 'Morgan White', username: 'morganwhite', email: 'morgan.white@example.com', location: 'Berlin, Germany', status: 'subscribed', avatar: { src: 'https://github.com/vitejs.png', alt: 'Morgan White' } },
+  { id: 5, name: 'Casey Gray', username: 'caseygray', email: 'casey.gray@example.com', location: 'Tokyo, Japan', status: 'subscribed', avatar: { src: 'https://github.com/vuejs.png', alt: 'Casey Gray' } },
+  { id: 6, name: 'Riley Davis', username: 'rileydavis', email: 'riley.davis@example.com', location: 'Sydney, Australia', status: 'subscribed', avatar: { src: 'https://github.com/unjs.png', alt: 'Riley Davis' } },
+  { id: 7, name: 'Jamie Johnson', username: 'jamiejohnson', email: 'jamie.johnson@example.com', location: 'Toronto, Canada', status: 'unsubscribed', avatar: { src: 'https://github.com/nitrojs.png', alt: 'Jamie Johnson' } },
+  { id: 8, name: 'Kelly Wilson', username: 'kellywilson', email: 'kelly.wilson@example.com', location: 'Madrid, Spain', status: 'subscribed', avatar: { src: 'https://github.com/vueuse.png', alt: 'Kelly Wilson' } }
+]
+
+const customerRowSelection = ref({ 1: true })
+const customerEmailFilter = ref('')
+const customerStatusFilter = ref('all')
+
+const displayedCustomers = computed(() => {
+  return customers.filter((customer) => {
+    if (customerStatusFilter.value !== 'all' && customer.status !== customerStatusFilter.value) {
+      return false
+    }
+    return customer.email.toLowerCase().includes(customerEmailFilter.value.toLowerCase())
+  })
+})
+
+const customerStatusItems = [
+  { label: 'All', value: 'all' },
+  { label: 'Subscribed', value: 'subscribed' },
+  { label: 'Unsubscribed', value: 'unsubscribed' },
+  { label: 'Bounced', value: 'bounced' }
+]
+
+const customerRowItems: DropdownMenuItem[] = [
+  { type: 'label', label: 'Actions' },
+  { label: 'Copy customer ID', icon: appConfig.ui.icons.copy },
+  { type: 'separator' },
+  { label: 'View customer details', icon: extra.list },
+  { type: 'separator' },
+  { label: 'Delete customer', icon: extra.trash, color: 'error' }
+]
+
+const customerColumns: TableColumn<Customer>[] = [{
+  id: 'select',
+  header: ({ table }) => h(UCheckbox, {
+    'modelValue': table.getIsSomePageRowsSelected() ? 'indeterminate' : table.getIsAllPageRowsSelected(),
+    'onUpdate:modelValue': (value: boolean | 'indeterminate') => table.toggleAllPageRowsSelected(!!value),
+    'ariaLabel': 'Select all'
+  }),
+  cell: ({ row }) => h(UCheckbox, {
+    'modelValue': row.getIsSelected(),
+    'onUpdate:modelValue': (value: boolean | 'indeterminate') => row.toggleSelected(!!value),
+    'ariaLabel': 'Select row'
+  })
+}, {
+  accessorKey: 'id',
+  header: 'ID'
+}, {
+  accessorKey: 'name',
+  header: 'Name',
+  cell: ({ row }) => {
+    return h('div', { class: 'flex items-center gap-3' }, [
+      h(UAvatar, { ...row.original.avatar, size: 'lg' }),
+      h('div', undefined, [
+        h('p', { class: 'font-medium text-highlighted' }, row.original.name),
+        h('p', undefined, `@${row.original.username}`)
+      ])
+    ])
+  }
+}, {
+  accessorKey: 'email',
+  header: 'Email'
+}, {
+  accessorKey: 'location',
+  header: 'Location'
+}, {
+  accessorKey: 'status',
+  header: 'Status',
+  cell: ({ row }) => {
+    const color = ({
+      subscribed: 'success' as const,
+      unsubscribed: 'error' as const,
+      bounced: 'warning' as const
+    })[row.original.status]
+
+    return h(UBadge, { class: 'capitalize', variant: 'subtle', color }, () => row.original.status)
+  }
+}, {
+  id: 'actions',
+  cell: () => {
+    return h('div', { class: 'text-right' }, h(
+      UDropdownMenu,
+      { content: { align: 'end' }, items: customerRowItems },
+      () => h(UButton, { icon: appConfig.ui.icons.ellipsis, color: 'neutral', variant: 'ghost', class: 'ml-auto' })
+    ))
+  }
+}]
+
+// Settings, mirrors app/pages/settings.vue + settings/index.vue + settings/notifications.vue,
+// trimmed to two sections without zod/UForm validation.
+const settingsLinks = computed<NavigationMenuItem[][]>(() => [[{
+  label: 'General',
+  icon: extra.user,
+  active: settingsSection.value === 'general',
+  onSelect: () => { settingsSection.value = 'general' }
+}, {
+  label: 'Notifications',
+  icon: extra.bell,
+  active: settingsSection.value === 'notifications',
+  onSelect: () => { settingsSection.value = 'notifications' }
+}]])
+
+const profile = reactive({
+  name: 'Benjamin Canac',
+  email: 'ben@nuxtlabs.com',
+  username: 'benjamincanac',
+  bio: ''
+})
+
+const profileFields = [
+  { name: 'name', label: 'Name', description: 'Will appear on receipts, invoices, and other communication.' },
+  { name: 'email', label: 'Email', description: 'Used to sign in, for email receipts and product updates.' },
+  { name: 'username', label: 'Username', description: 'Your unique username for logging in and your profile URL.' }
+] as const
+
+const notificationsState = reactive<{ [key: string]: boolean }>({
+  email: true,
+  desktop: false,
+  weekly_digest: false,
+  product_updates: true
+})
+
+const notificationSections = [{
+  title: 'Notification channels',
+  description: 'Where can we notify you?',
+  fields: [
+    { name: 'email', label: 'Email', description: 'Receive a daily email digest.' },
+    { name: 'desktop', label: 'Desktop', description: 'Receive desktop notifications.' }
+  ]
+}, {
+  title: 'Account updates',
+  description: 'Receive updates about Nuxt UI.',
+  fields: [
+    { name: 'weekly_digest', label: 'Weekly digest', description: 'Receive a weekly digest of news.' },
+    { name: 'product_updates', label: 'Product updates', description: 'Receive a monthly email with all new features and updates.' }
+  ]
+}]
+
+const customerPage = ref(1)
+
+watch([customerEmailFilter, customerStatusFilter], () => {
+  customerPage.value = 1
+})
+
+const paginatedCustomers = computed(() => {
+  return displayedCustomers.value.slice((customerPage.value - 1) * 5, customerPage.value * 5)
+})
+
+const selectedCustomersCount = computed(() => {
+  return Object.values(customerRowSelection.value).filter(Boolean).length
+})
+
+const pageTitles: Record<Page, string> = {
+  home: 'Home',
+  inbox: 'Inbox',
+  customers: 'Customers',
+  settings: 'Settings'
+}
+</script>
+
+<template>
+  <!-- UDashboardGroup is `fixed inset-0` by default: contain it in the preview pane instead. -->
+  <UDashboardGroup
+    unit="rem"
+    :persistent="false"
+    class="relative inset-auto h-full w-full"
+  >
+    <UDashboardSidebar
+      collapsible
+      resizable
+      class="bg-elevated/25"
+      :ui="{ root: 'flex min-h-0', footer: 'border-t border-default' }"
+    >
+      <template #header="{ collapsed }">
+        <UDropdownMenu
+          :items="teamItems"
+          :content="{ align: 'center', collisionPadding: 12 }"
+          :ui="{ content: collapsed ? 'w-40' : 'w-(--reka-dropdown-menu-trigger-width)' }"
+        >
+          <UButton
+            v-bind="{
+              ...selectedTeam,
+              label: collapsed ? undefined : selectedTeam.label,
+              trailingIcon: collapsed ? undefined : extra.sort
+            }"
+            color="neutral"
+            variant="ghost"
+            block
+            :square="collapsed"
+            class="data-[state=open]:bg-elevated"
+            :class="[!collapsed && 'py-2']"
+            :ui="{ trailingIcon: 'text-dimmed' }"
+          />
+        </UDropdownMenu>
+      </template>
+
+      <template #default="{ collapsed }">
+        <UDashboardSearchButton :collapsed="collapsed" class="bg-transparent ring-default" />
+
+        <UNavigationMenu
+          :collapsed="collapsed"
+          :items="links[0]"
+          orientation="vertical"
+          tooltip
+          popover
+        />
+
+        <UNavigationMenu
+          :collapsed="collapsed"
+          :items="links[1]"
+          orientation="vertical"
+          tooltip
+          class="mt-auto"
+        />
+      </template>
+
+      <template #footer="{ collapsed }">
+        <UDropdownMenu
+          :items="userItems"
+          :content="{ align: 'center', collisionPadding: 12 }"
+          :ui="{ content: collapsed ? 'w-48' : 'w-(--reka-dropdown-menu-trigger-width)' }"
+        >
+          <UButton
+            v-bind="{
+              ...user,
+              label: collapsed ? undefined : user.name,
+              trailingIcon: collapsed ? undefined : extra.sort
+            }"
+            color="neutral"
+            variant="ghost"
+            block
+            :square="collapsed"
+            class="data-[state=open]:bg-elevated"
+            :ui="{ trailingIcon: 'text-dimmed' }"
+          />
+        </UDropdownMenu>
+      </template>
+    </UDashboardSidebar>
+
+    <!-- Inbox replicates the template's split list / mail panes, so it swaps the whole panel. -->
+    <template v-if="page === 'inbox'">
+      <UDashboardPanel
+        id="theme-studio-inbox-list"
+        resizable
+        :default-size="35"
+        :min-size="25"
+        :max-size="45"
+        :ui="{ root: 'min-h-0' }"
+      >
+        <UDashboardNavbar title="Inbox">
+          <template #leading>
+            <UDashboardSidebarCollapse />
+          </template>
+          <template #trailing>
+            <UBadge :label="String(filteredMails.length)" variant="subtle" />
+          </template>
+
+          <template #right>
+            <UTabs
+              v-model="selectedMailTab"
+              :items="mailTabItems"
+              :content="false"
+              size="xs"
+            />
+          </template>
+        </UDashboardNavbar>
+
+        <div class="overflow-y-auto divide-y divide-default">
+          <div v-for="mail in filteredMails" :key="mail.id">
+            <div
+              class="p-4 sm:px-6 text-sm cursor-pointer border-l-2 transition-colors"
+              :class="[
+                mail.unread ? 'text-highlighted' : 'text-toned',
+                selectedMail && selectedMail.id === mail.id
+                  ? 'border-primary bg-primary/10'
+                  : 'border-bg hover:border-primary hover:bg-primary/5'
+              ]"
+              @click="selectedMail = mail"
+            >
+              <div class="flex items-center justify-between" :class="[mail.unread && 'font-semibold']">
+                <div class="flex items-center gap-3">
+                  {{ mail.from.name }}
+
+                  <UChip v-if="mail.unread" />
+                </div>
+
+                <span>{{ mail.date }}</span>
+              </div>
+              <p class="truncate" :class="[mail.unread && 'font-semibold']">
+                {{ mail.subject }}
+              </p>
+              <p class="text-dimmed line-clamp-1">
+                {{ mail.body }}
+              </p>
+            </div>
+          </div>
+        </div>
+      </UDashboardPanel>
+
+      <UDashboardPanel v-if="selectedMail" id="theme-studio-inbox-mail" :ui="{ root: 'min-h-0' }">
+        <UDashboardNavbar :title="selectedMail.subject" :toggle="false">
+          <template #leading>
+            <UButton
+              :icon="appConfig.ui.icons.close"
+              color="neutral"
+              variant="ghost"
+              class="-ms-1.5"
+              @click="selectedMail = null"
+            />
+          </template>
+
+          <template #right>
+            <UTooltip text="Archive">
+              <UButton :icon="extra.inbox" color="neutral" variant="ghost" />
+            </UTooltip>
+
+            <UTooltip text="Reply">
+              <UButton :icon="extra.reply" color="neutral" variant="ghost" />
+            </UTooltip>
+
+            <UDropdownMenu :items="mailDropdownItems">
+              <UButton :icon="appConfig.ui.icons.ellipsis" color="neutral" variant="ghost" />
+            </UDropdownMenu>
+          </template>
+        </UDashboardNavbar>
+
+        <div class="flex flex-col sm:flex-row justify-between gap-1 p-4 sm:px-6 border-b border-default">
+          <div class="flex items-start gap-4 sm:my-1.5">
+            <UAvatar v-bind="selectedMail.from.avatar" size="3xl" />
+
+            <div class="min-w-0">
+              <p class="font-semibold text-highlighted">
+                {{ selectedMail.from.name }}
+              </p>
+              <p class="text-muted">
+                {{ selectedMail.from.email }}
+              </p>
+            </div>
+          </div>
+
+          <p class="max-sm:pl-16 text-muted text-sm sm:mt-2">
+            {{ selectedMail.datetime }}
+          </p>
+        </div>
+
+        <div class="flex-1 p-4 sm:p-6 overflow-y-auto">
+          <p class="whitespace-pre-wrap">
+            {{ selectedMail.body }}
+          </p>
+        </div>
+
+        <div class="pb-4 px-4 sm:px-6 shrink-0">
+          <UCard variant="subtle" class="mt-auto" :ui="{ header: 'flex items-center gap-1.5 text-dimmed' }">
+            <template #header>
+              <UIcon :name="extra.reply" class="size-5" />
+
+              <span class="text-sm truncate">
+                Reply to {{ selectedMail.from.name }} ({{ selectedMail.from.email }})
+              </span>
+            </template>
+
+            <form @submit.prevent>
+              <UTextarea
+                v-model="reply"
+                color="neutral"
+                variant="none"
+                autoresize
+                placeholder="Write your reply..."
+                :rows="4"
+                class="w-full"
+                :ui="{ base: 'p-0 resize-none' }"
+              />
+
+              <div class="flex items-center justify-between">
+                <UButton color="neutral" variant="ghost" :icon="extra.paperclip" aria-label="Attach file" />
+
+                <UButton type="submit" color="neutral" label="Send" :icon="extra.send" />
+              </div>
+            </form>
+          </UCard>
+        </div>
+      </UDashboardPanel>
+      <div v-else class="flex-1 hidden lg:flex items-center justify-center">
+        <UIcon :name="extra.inbox" class="size-32 text-dimmed" />
+      </div>
+    </template>
+
+    <UDashboardPanel v-else :ui="{ root: 'min-h-0' }">
+      <template #header>
+        <UDashboardNavbar :title="pageTitles[page]" :ui="{ right: 'gap-3' }">
+          <template #leading>
+            <UDashboardSidebarCollapse />
+          </template>
+
+          <template #right>
+            <UTooltip text="Notifications" :shortcuts="['N']">
+              <UButton color="neutral" variant="ghost" square aria-label="Notifications">
+                <UChip color="error" inset>
+                  <UIcon :name="extra.bell" class="size-5 shrink-0" />
+                </UChip>
+              </UButton>
+            </UTooltip>
+
+            <UButton
+              v-if="page === 'customers'"
+              label="New customer"
+              :icon="appConfig.ui.icons.plus"
+            />
+            <UDropdownMenu v-else :items="newItems">
+              <UButton :icon="appConfig.ui.icons.plus" class="rounded-full" aria-label="New" />
+            </UDropdownMenu>
+          </template>
+        </UDashboardNavbar>
+
+        <UDashboardToolbar v-if="page === 'home'">
+          <template #left>
+            <UButton
+              color="neutral"
+              variant="ghost"
+              :icon="extra.calendar"
+              label="Jun 22 - Jul 6, 2026"
+              class="-ms-1"
+            />
+
+            <USelect v-model="period" :items="periodItems" class="w-28" />
+          </template>
+        </UDashboardToolbar>
+
+        <UDashboardToolbar v-else-if="page === 'settings'">
+          <UNavigationMenu :items="settingsLinks" highlight class="-mx-1 flex-1" />
+        </UDashboardToolbar>
+      </template>
+
+      <template #body>
+        <!-- The preview pane is far narrower than the real template's page,
+             two-up until xl, and the joined-border look only when four fit. -->
+        <!-- shrink-0 everywhere: the panel body is a scrollable flex column,
+             and a shrinking child gets crushed into its own overflow-hidden -->
+        <template v-if="page === 'home'">
+          <UPageGrid class="shrink-0 grid-cols-2 xl:grid-cols-4 gap-4 xl:gap-px">
+            <UPageCard
+              v-for="stat in stats"
+              :key="stat.title"
+              :icon="stat.icon"
+              :title="stat.title"
+              :ui="{
+                container: 'gap-y-1.5',
+                wrapper: 'items-start',
+                leading: 'p-2.5 rounded-full bg-primary/10 ring ring-inset ring-primary/25 flex-col',
+                title: 'font-normal text-muted text-xs uppercase'
+              }"
+              class="xl:rounded-none xl:first:rounded-l-lg xl:last:rounded-r-lg hover:z-1"
+            >
+              <div class="flex items-center gap-2 flex-wrap min-w-0">
+                <span class="text-2xl font-semibold text-highlighted">
+                  {{ stat.value }}
+                </span>
+
+                <UBadge :color="stat.variation > 0 ? 'success' : 'error'" class="text-xs">
+                  {{ stat.variation > 0 ? '+' : '' }}{{ stat.variation }}%
+                </UBadge>
+              </div>
+            </UPageCard>
+          </UPageGrid>
+
+          <UCard class="shrink-0" :ui="{ body: 'px-0! pt-0! pb-3!' }">
+            <template #header>
+              <div>
+                <p class="text-xs text-muted uppercase mb-1.5">
+                  Revenue
+                </p>
+                <p class="text-3xl text-highlighted font-semibold">
+                  {{ revenueTotal }}
+                </p>
+              </div>
+            </template>
+
+            <svg
+              viewBox="0 0 400 120"
+              preserveAspectRatio="none"
+              class="w-full h-40 text-primary"
+              aria-hidden="true"
+            >
+              <polygon :points="chartArea" fill="currentColor" class="opacity-10" />
+              <polyline
+                :points="chartPoints"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="1.5"
+                vector-effect="non-scaling-stroke"
+              />
+            </svg>
+
+            <div class="flex items-center justify-between px-4 sm:px-6 pt-2 text-xs text-dimmed">
+              <span v-for="tick in chartTicks" :key="tick">{{ tick }}</span>
+            </div>
+          </UCard>
+
+          <UTable
+            :data="sales"
+            :columns="salesColumns"
+            class="shrink-0"
+            :ui="{
+              base: 'table-fixed border-separate border-spacing-0',
+              thead: '[&>tr]:bg-elevated/50 [&>tr]:after:content-none',
+              tbody: '[&>tr]:last:[&>td]:border-b-0',
+              th: 'first:rounded-l-lg last:rounded-r-lg border-y border-default first:border-l last:border-r',
+              td: 'border-b border-default'
+            }"
+          />
+        </template>
+
+        <template v-else-if="page === 'customers'">
+          <div class="flex flex-wrap items-center justify-between gap-1.5 shrink-0">
+            <UInput
+              v-model="customerEmailFilter"
+              class="max-w-sm"
+              :icon="appConfig.ui.icons.search"
+              placeholder="Filter emails..."
+            />
+
+            <div class="flex flex-wrap items-center gap-1.5">
+              <UButton
+                v-if="selectedCustomersCount"
+                label="Delete"
+                color="error"
+                variant="subtle"
+                :icon="extra.trash"
+              >
+                <template #trailing>
+                  <UKbd>{{ selectedCustomersCount }}</UKbd>
+                </template>
+              </UButton>
+
+              <USelect
+                v-model="customerStatusFilter"
+                :items="customerStatusItems"
+                :ui="{ trailingIcon: 'group-data-[state=open]:rotate-180 transition-transform duration-200' }"
+                placeholder="Filter status"
+                class="min-w-28"
+              />
+            </div>
+          </div>
+
+          <UTable
+            v-model:row-selection="customerRowSelection"
+            :data="paginatedCustomers"
+            :columns="customerColumns"
+            class="shrink-0"
+            :ui="{
+              base: 'table-fixed border-separate border-spacing-0',
+              thead: '[&>tr]:bg-elevated/50 [&>tr]:after:content-none',
+              tbody: '[&>tr]:last:[&>td]:border-b-0',
+              th: 'py-2 first:rounded-l-lg last:rounded-r-lg border-y border-default first:border-l last:border-r',
+              td: 'border-b border-default'
+            }"
+          />
+
+          <div class="flex items-center justify-between gap-3 border-t border-default pt-4 mt-auto shrink-0">
+            <div class="text-sm text-muted">
+              {{ selectedCustomersCount }} of {{ displayedCustomers.length }} row(s) selected.
+            </div>
+
+            <UPagination
+              v-model:page="customerPage"
+              :items-per-page="5"
+              :total="displayedCustomers.length"
+            />
+          </div>
+        </template>
+
+        <div v-else-if="page === 'settings'" class="flex flex-col gap-4 sm:gap-6 w-full lg:max-w-2xl mx-auto shrink-0">
+          <template v-if="settingsSection === 'general'">
+            <UPageCard
+              title="Profile"
+              description="These informations will be displayed publicly."
+              variant="naked"
+              orientation="horizontal"
+            >
+              <UButton label="Save changes" color="neutral" class="w-fit lg:ms-auto" />
+            </UPageCard>
+
+            <UPageCard variant="subtle">
+              <template v-for="(field, index) in profileFields" :key="field.name">
+                <USeparator v-if="index > 0" />
+
+                <UFormField
+                  :name="field.name"
+                  :label="field.label"
+                  :description="field.description"
+                  required
+                  class="flex max-sm:flex-col justify-between items-start gap-4"
+                >
+                  <UInput v-model="profile[field.name]" autocomplete="off" />
+                </UFormField>
+              </template>
+              <USeparator />
+              <UFormField
+                name="bio"
+                label="Bio"
+                description="Brief description for your profile."
+                class="flex max-sm:flex-col justify-between items-start gap-4"
+                :ui="{ container: 'w-full' }"
+              >
+                <UTextarea v-model="profile.bio" :rows="4" autoresize class="w-full" />
+              </UFormField>
+            </UPageCard>
+          </template>
+
+          <template v-else>
+            <div v-for="(section, index) in notificationSections" :key="index">
+              <UPageCard
+                :title="section.title"
+                :description="section.description"
+                variant="naked"
+                class="mb-4"
+              />
+
+              <UPageCard variant="subtle" :ui="{ container: 'divide-y divide-default' }">
+                <UFormField
+                  v-for="field in section.fields"
+                  :key="field.name"
+                  :name="field.name"
+                  :label="field.label"
+                  :description="field.description"
+                  class="flex items-center justify-between not-last:pb-4 gap-2"
+                >
+                  <USwitch v-model="notificationsState[field.name]" />
+                </UFormField>
+              </UPageCard>
+            </div>
+          </template>
+        </div>
+      </template>
+    </UDashboardPanel>
+  </UDashboardGroup>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioViewDocs.vue b/docs/app/components/theme-studio/ThemeStudioViewDocs.vue
new file mode 100644
index 0000000000..ef35d5a306
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioViewDocs.vue
@@ -0,0 +1,322 @@
+<script setup lang="ts">
+import type { DropdownMenuItem, NavigationMenuItem, PageLink } from '@nuxt/ui'
+
+const appConfig = useAppConfig()
+const extra = useStudioExtraIcons()
+
+// Left aside: the template renders UContentNavigation from @nuxt/content,
+// content-coupled, so the same tree is faked with a vertical UNavigationMenu.
+const navLinks: NavigationMenuItem[] = [{
+  label: 'Getting Started',
+  type: 'trigger',
+  defaultOpen: true,
+  children: [
+    { label: 'Introduction', icon: extra.home },
+    { label: 'Installation', icon: 'i-lucide-download' },
+    { label: 'Usage', icon: extra.settings, active: true }
+  ]
+}, {
+  label: 'Essentials',
+  type: 'trigger',
+  defaultOpen: true,
+  children: [
+    { label: 'Markdown Syntax', icon: extra.heading },
+    { label: 'Code Blocks', icon: 'i-lucide-code' },
+    { label: 'Prose Components', icon: 'i-lucide-component' },
+    { label: 'Images & Embeds', icon: extra.image }
+  ]
+}, {
+  label: 'AI',
+  type: 'trigger',
+  defaultOpen: true,
+  children: [
+    { label: 'MCP Server', icon: 'i-lucide-bot' },
+    { label: 'LLMs.txt', icon: appConfig.ui.icons.file }
+  ]
+}]
+
+// PageHeaderLinks dropdown, minus the real clipboard / external navigations.
+const copyItems: DropdownMenuItem[] = [
+  { label: 'Copy Markdown link', icon: extra.link },
+  { label: 'View as Markdown', icon: 'i-simple-icons:markdown' },
+  { label: 'Open in ChatGPT', icon: 'i-simple-icons:openai' },
+  { label: 'Open in Claude', icon: 'i-simple-icons:anthropic' }
+]
+
+// Right column: UContentToc is content-coupled and router-driven, so the
+// same sticky layout is hand-rolled with faked active states.
+const tocLinks = [
+  { label: 'Writing content', active: true },
+  {
+    label: 'App Configuration',
+    children: [
+      { label: 'Header' },
+      { label: 'Footer' },
+      { label: 'Table of contents' }
+    ]
+  }
+]
+
+const communityLinks: PageLink[] = [
+  { label: 'Edit this page', icon: appConfig.ui.icons.external },
+  { label: 'Star on GitHub', icon: appConfig.ui.icons.star },
+  { label: 'Releases', icon: 'i-lucide-rocket' }
+]
+
+const frontmatterFields = [
+  { key: 'title', type: 'string', description: 'Page title, shown in the header and navigation' },
+  { key: 'description', type: 'string', description: 'Page description, shown below the title' },
+  { key: 'navigation.icon', type: 'string', description: 'Icon displayed next to the link in the aside' }
+]
+
+const appConfigCode = `export default defineAppConfig({
+  header: {
+    title: 'Docs',
+    to: '/',
+    // Show or hide the search bar
+    search: true,
+    // Show or hide the color mode button
+    colorMode: true,
+    links: [{
+      'icon': 'i-simple-icons-github',
+      'to': 'https://github.com/nuxt-ui-templates/docs',
+      'target': '_blank',
+      'aria-label': 'GitHub'
+    }]
+  }
+})`
+</script>
+
+<template>
+  <!-- The pane is the scroll container, so the header and asides stick to it. -->
+  <div class="h-full overflow-y-auto bg-default">
+    <UHeader :toggle="false" class="rounded-t-[inherit]" :ui="{ center: 'flex-1' }">
+      <template #left>
+        <div class="flex items-center gap-1.5">
+          <UIcon :name="extra.bookOpen" class="size-6 text-primary shrink-0" />
+          <span class="text-xl font-bold text-highlighted">Docs</span>
+        </div>
+      </template>
+
+      <!-- UContentSearchButton opens the content search modal: fake the expanded look. -->
+      <UButton
+        :icon="appConfig.ui.icons.search"
+        label="Search documentation..."
+        color="neutral"
+        variant="outline"
+        class="w-full"
+        :ui="{ base: 'text-dimmed hover:text-default font-normal', leadingIcon: 'size-4' }"
+      >
+        <template #trailing>
+          <div class="ms-auto hidden lg:flex items-center gap-0.5">
+            <UKbd value="meta" />
+            <UKbd value="K" />
+          </div>
+        </template>
+      </UButton>
+
+      <template #right>
+        <UButton icon="i-lucide-sun-moon" aria-label="Color mode" color="neutral" variant="ghost" />
+        <UButton :icon="extra.github" aria-label="GitHub" color="neutral" variant="ghost" />
+      </template>
+    </UHeader>
+
+    <UContainer>
+      <UPage>
+        <template #left>
+          <UPageAside>
+            <UNavigationMenu
+              :items="navLinks"
+              orientation="vertical"
+              highlight
+              :ui="{ linkTrailingIcon: 'group-data-[state=open]:rotate-180 transition-transform duration-200' }"
+            />
+          </UPageAside>
+        </template>
+
+        <UPage>
+          <UPageHeader
+            headline="Getting Started"
+            title="Usage"
+            description="Learn how to write and customize your documentation."
+          >
+            <template #links>
+              <UFieldGroup>
+                <UButton
+                  label="Copy page"
+                  :icon="appConfig.ui.icons.copy"
+                  color="neutral"
+                  variant="outline"
+                  :ui="{ leadingIcon: 'text-neutral size-3.5' }"
+                />
+                <UDropdownMenu
+                  :items="copyItems"
+                  :content="{ align: 'end', side: 'bottom', sideOffset: 8 }"
+                  :ui="{ content: 'w-48' }"
+                >
+                  <UButton
+                    :icon="appConfig.ui.icons.chevronDown"
+                    size="sm"
+                    color="neutral"
+                    variant="outline"
+                    aria-label="Open copy actions menu"
+                  />
+                </UDropdownMenu>
+              </UFieldGroup>
+            </template>
+          </UPageHeader>
+
+          <UPageBody>
+            <ProseP>
+              This is only a basic example of what you can achieve with
+              <span class="text-primary font-medium border-b border-transparent hover:border-primary cursor-pointer">Nuxt UI</span>,
+              you can tweak it to match your needs. The template uses several Nuxt modules underneath like
+              <ProseCode>@nuxt/content</ProseCode> for the content and <ProseCode>nuxt-og-image</ProseCode>
+              for social previews.
+            </ProseP>
+
+            <ProseTip>
+              Learn more on how to take the most out of Nuxt UI!
+            </ProseTip>
+
+            <ProseH2>
+              Writing content
+            </ProseH2>
+
+            <ProseP>
+              You can just start writing <ProseCode>.md</ProseCode> or <ProseCode>.yml</ProseCode> files in the
+              <ProseCode>content/</ProseCode> directory to have your pages updated. The navigation will be
+              automatically generated in the left aside and in the mobile menu. You will also be able to go
+              through your content with full-text search.
+            </ProseP>
+
+            <ProseP>
+              Each page supports a few frontmatter fields to customize how it appears:
+            </ProseP>
+
+            <ProseTable>
+              <ProseThead>
+                <ProseTr>
+                  <ProseTh>Key</ProseTh>
+                  <ProseTh>Type</ProseTh>
+                  <ProseTh>Description</ProseTh>
+                </ProseTr>
+              </ProseThead>
+              <ProseTbody>
+                <ProseTr v-for="field in frontmatterFields" :key="field.key">
+                  <ProseTd>
+                    <ProseCode>{{ field.key }}</ProseCode>
+                  </ProseTd>
+                  <ProseTd>
+                    <ProseCode>{{ field.type }}</ProseCode>
+                  </ProseTd>
+                  <ProseTd>{{ field.description }}</ProseTd>
+                </ProseTr>
+              </ProseTbody>
+            </ProseTable>
+
+            <ProseH2>
+              App Configuration
+            </ProseH2>
+
+            <ProseP>
+              In addition to <ProseCode>@nuxt/ui</ProseCode> configuration through the
+              <ProseCode>app.config.ts</ProseCode>, this template lets you customize the
+              <ProseCode>Header</ProseCode>, <ProseCode>Footer</ProseCode> and the
+              <ProseCode>Table of contents</ProseCode> components.
+            </ProseP>
+
+            <ProseH3>
+              Header
+            </ProseH3>
+
+            <ProsePre filename="app.config.ts" :icon="extra.settings" :code="appConfigCode">
+              {{ appConfigCode }}
+            </ProsePre>
+
+            <ProseH3>
+              Footer
+            </ProseH3>
+
+            <ProseP>
+              The footer follows the same pattern: update the bottom left credits, toggle the color mode
+              button and customize the social links, all from a single object in your app config.
+            </ProseP>
+
+            <USeparator />
+
+            <!-- UContentSurround is content-coupled: same prev/next look with a UPageCard pair. -->
+            <div class="grid grid-cols-1 sm:grid-cols-2 gap-8">
+              <UPageCard
+                :icon="appConfig.ui.icons.arrowLeft"
+                title="Installation"
+                description="Get started with the documentation template in a few steps."
+                variant="outline"
+                :ui="{ leadingIcon: 'text-muted group-hover:text-primary transition-colors' }"
+              />
+              <UPageCard
+                :icon="appConfig.ui.icons.arrowRight"
+                title="Markdown Syntax"
+                description="Headings, lists, links and everything Markdown supports."
+                variant="outline"
+                class="text-right"
+                :ui="{ wrapper: 'items-end', leadingIcon: 'text-muted group-hover:text-primary transition-colors' }"
+              />
+            </div>
+          </UPageBody>
+
+          <template #right>
+            <div class="hidden lg:flex flex-col gap-6 sticky top-(--ui-header-height) py-8">
+              <div>
+                <p class="text-sm font-semibold text-highlighted mb-1.5">
+                  Table of Contents
+                </p>
+
+                <ul class="min-w-0">
+                  <li v-for="link in tocLinks" :key="link.label" class="min-w-0">
+                    <button
+                      type="button"
+                      class="w-full text-start text-sm py-1 truncate transition-colors"
+                      :class="link.active ? 'text-primary' : 'text-muted hover:text-default'"
+                    >
+                      {{ link.label }}
+                    </button>
+
+                    <ul v-if="link.children" class="ms-3 min-w-0">
+                      <li v-for="child in link.children" :key="child.label" class="min-w-0">
+                        <button
+                          type="button"
+                          class="w-full text-start text-sm py-1 truncate text-muted hover:text-default transition-colors"
+                        >
+                          {{ child.label }}
+                        </button>
+                      </li>
+                    </ul>
+                  </li>
+                </ul>
+              </div>
+
+              <USeparator type="dashed" />
+
+              <UPageLinks title="Community" :links="communityLinks" />
+            </div>
+          </template>
+        </UPage>
+      </UPage>
+    </UContainer>
+
+    <UFooter>
+      <template #left>
+        <p class="text-sm text-muted">
+          Built with Nuxt UI • © 2026
+        </p>
+      </template>
+
+      <template #right>
+        <UButton icon="i-simple-icons-discord" aria-label="Discord" color="neutral" variant="ghost" />
+        <UButton icon="i-simple-icons-x" aria-label="X" color="neutral" variant="ghost" />
+        <UButton :icon="extra.github" aria-label="GitHub" color="neutral" variant="ghost" />
+      </template>
+    </UFooter>
+  </div>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioViewEditor.vue b/docs/app/components/theme-studio/ThemeStudioViewEditor.vue
new file mode 100644
index 0000000000..c8bc9b995e
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioViewEditor.vue
@@ -0,0 +1,304 @@
+<script setup lang="ts">
+import type { DropdownMenuItem, EditorSuggestionMenuItem, EditorToolbarItem } from '@nuxt/ui'
+import type { Editor, JSONContent } from '@tiptap/vue-3'
+import { upperFirst } from 'scule'
+import { mapEditorItems } from '@nuxt/ui/utils/editor'
+
+const appConfig = useAppConfig()
+const extra = useStudioExtraIcons()
+
+/**
+ * Self-contained replica of the official Nuxt UI Editor template
+ * (github.com/nuxt-ui-templates/editor): header chrome with a fixed
+ * toolbar, a bubble toolbar on selection, slash commands and a drag
+ * handle over a markdown document. Collaboration, AI completions,
+ * image upload, tables and task lists are omitted, they need server
+ * routes or extensions the docs app doesn't ship.
+ */
+
+const content = ref(`# Nuxt Editor Template
+
+A Notion-like WYSIWYG editor built with [Vue](https://vuejs.org/) & [Nuxt](https://nuxt.com/), and themed live by this studio.
+
+> Select some text to reveal the bubble toolbar, or type \`/\` on an empty line for quick commands.
+
+---
+
+## Rich Text Editing
+
+Full formatting support with **bold**, *italic*, <u>underline</u>, ~~strikethrough~~, and \`inline code\`.
+
+### Lists
+
+1. Numbered lists for sequential items
+2. With automatic numbering
+
+- Bullet lists work too
+  - With nested items
+  - At multiple levels
+
+### Code Blocks
+
+\`\`\`vue
+<template>
+  <UEditor v-slot="{ editor }" v-model="value" content-type="markdown">
+    <UEditorToolbar :editor="editor" :items="items" />
+  </UEditor>
+</template>
+\`\`\`
+
+## Features
+
+### Bubble & Fixed Toolbars
+
+Select text to see the bubble toolbar with formatting options. The fixed toolbar at the top provides quick access to common actions.
+
+### Drag Handle
+
+Use the drag handle on the left side of any block to reorder, duplicate, delete, or convert between block types.
+
+### Slash Commands
+
+Type \`/\` anywhere to access quick insertion commands for headings, lists, code blocks and more.
+
+---
+
+Every heading, quote and code block above is styled by the semantic tokens you are editing right now.
+`)
+
+const headingItems = [1, 2, 3, 4].map(level => ({
+  kind: 'heading' as const,
+  level,
+  label: `Heading ${level}`,
+  icon: `i-lucide-heading-${level}`
+}))
+
+const blockItems = [{
+  kind: 'bulletList' as const,
+  label: 'Bullet List',
+  icon: extra.list
+}, {
+  kind: 'orderedList' as const,
+  label: 'Ordered List',
+  icon: 'i-lucide-list-ordered'
+}, {
+  kind: 'blockquote' as const,
+  label: 'Blockquote',
+  icon: 'i-lucide-text-quote'
+}, {
+  kind: 'codeBlock' as const,
+  label: 'Code Block',
+  icon: 'i-lucide-square-code'
+}]
+
+const markItems = [{
+  kind: 'mark' as const,
+  mark: 'bold' as const,
+  icon: 'i-lucide-bold',
+  tooltip: { text: 'Bold' }
+}, {
+  kind: 'mark' as const,
+  mark: 'italic' as const,
+  icon: 'i-lucide-italic',
+  tooltip: { text: 'Italic' }
+}, {
+  kind: 'mark' as const,
+  mark: 'underline' as const,
+  icon: 'i-lucide-underline',
+  tooltip: { text: 'Underline' }
+}, {
+  kind: 'mark' as const,
+  mark: 'strike' as const,
+  icon: 'i-lucide-strikethrough',
+  tooltip: { text: 'Strikethrough' }
+}, {
+  kind: 'mark' as const,
+  mark: 'code' as const,
+  icon: 'i-lucide-code',
+  tooltip: { text: 'Code' }
+}]
+
+const toolbarItems: EditorToolbarItem[][] = [[{
+  kind: 'undo',
+  icon: extra.undo,
+  tooltip: { text: 'Undo' }
+}, {
+  kind: 'redo',
+  icon: extra.redo,
+  tooltip: { text: 'Redo' }
+}], [{
+  icon: extra.heading,
+  tooltip: { text: 'Headings' },
+  content: { align: 'start' },
+  items: headingItems
+}, ...blockItems.map(({ label, ...item }) => ({ ...item, tooltip: { text: label } }))], markItems]
+
+const bubbleToolbarItems: EditorToolbarItem[][] = [[{
+  label: 'Turn into',
+  trailingIcon: appConfig.ui.icons.chevronDown,
+  activeColor: 'neutral',
+  activeVariant: 'ghost',
+  tooltip: { text: 'Turn into' },
+  content: { align: 'start' },
+  ui: { label: 'text-xs' },
+  items: [{
+    type: 'label',
+    label: 'Turn into'
+  }, {
+    kind: 'paragraph',
+    label: 'Paragraph',
+    icon: 'i-lucide-type'
+  }, ...headingItems, ...blockItems]
+}], markItems]
+
+const suggestionItems: EditorSuggestionMenuItem[][] = [[{
+  type: 'label',
+  label: 'Style'
+}, {
+  kind: 'paragraph',
+  label: 'Paragraph',
+  icon: 'i-lucide-type'
+}, ...headingItems, ...blockItems], [{
+  type: 'label',
+  label: 'Insert'
+}, {
+  kind: 'horizontalRule',
+  label: 'Horizontal Rule',
+  icon: 'i-lucide-separator-horizontal'
+}]]
+
+const selectedNode = ref<{ node: JSONContent, pos: number }>()
+
+function dragHandleItems(editor: Editor): DropdownMenuItem[][] {
+  if (!selectedNode.value?.node?.type) {
+    return []
+  }
+
+  const pos = selectedNode.value.pos
+
+  return mapEditorItems(editor, [[{
+    type: 'label',
+    label: upperFirst(selectedNode.value.node.type)
+  }, {
+    label: 'Turn into',
+    icon: 'i-lucide-repeat-2',
+    children: [{ kind: 'paragraph', label: 'Paragraph', icon: 'i-lucide-type' }, ...headingItems, ...blockItems]
+  }], [{
+    kind: 'duplicate',
+    pos,
+    label: 'Duplicate',
+    icon: appConfig.ui.icons.copy
+  }, {
+    kind: 'moveUp',
+    pos,
+    label: 'Move up',
+    icon: appConfig.ui.icons.arrowUp
+  }, {
+    kind: 'moveDown',
+    pos,
+    label: 'Move down',
+    icon: appConfig.ui.icons.arrowDown
+  }], [{
+    kind: 'delete',
+    pos,
+    label: 'Delete',
+    icon: extra.trash
+  }]]) as DropdownMenuItem[][]
+}
+</script>
+
+<template>
+  <div class="h-full overflow-y-auto bg-default">
+    <ClientOnly>
+      <UEditor
+        v-slot="{ editor, handlers }"
+        v-model="content"
+        content-type="markdown"
+        placeholder="Write, type '/' for commands..."
+        class="min-h-full"
+        :ui="{ base: 'p-4 sm:p-10', content: 'max-w-3xl mx-auto' }"
+      >
+        <header class="sticky top-0 z-10 h-14 flex items-center gap-2 border-b border-default bg-default/75 backdrop-blur px-4">
+          <div class="flex items-center gap-1.5 shrink-0">
+            <UIcon name="i-lucide-notebook-pen" class="size-5 text-primary" />
+            <span class="text-base font-bold text-highlighted hidden sm:inline">Editor</span>
+          </div>
+
+          <div class="flex-1 min-w-0 flex justify-end overflow-x-auto py-1">
+            <UEditorToolbar :editor="editor" :items="toolbarItems" />
+          </div>
+
+          <USeparator orientation="vertical" class="h-7 shrink-0" />
+
+          <div class="flex items-center gap-2 shrink-0">
+            <UAvatarGroup size="2xs">
+              <UAvatar alt="Anna Cooper" chip />
+              <UAvatar alt="Ben Rogers" chip />
+            </UAvatarGroup>
+
+            <UButton
+              label="Share"
+              :icon="extra.users"
+              color="neutral"
+              variant="outline"
+              size="sm"
+              class="hidden sm:inline-flex"
+            />
+          </div>
+        </header>
+
+        <UEditorToolbar
+          :editor="editor"
+          :items="bubbleToolbarItems"
+          layout="bubble"
+          :should-show="({ view, state }) => view.hasFocus() && !state.selection.empty"
+        />
+
+        <UEditorSuggestionMenu :editor="editor" :items="suggestionItems" />
+
+        <UEditorDragHandle v-slot="{ ui, onClick }" :editor="editor" @node-change="selectedNode = $event">
+          <UButton
+            :icon="appConfig.ui.icons.plus"
+            color="neutral"
+            variant="ghost"
+            size="sm"
+            :class="ui.handle()"
+            @click="(e) => {
+              e.stopPropagation()
+              const selected = onClick()
+              handlers.suggestion?.execute(editor, { pos: selected?.pos }).run()
+            }"
+          />
+
+          <UDropdownMenu
+            v-slot="{ open }"
+            :modal="false"
+            :items="dragHandleItems(editor)"
+            :content="{ side: 'left' }"
+            :ui="{ content: 'w-48', label: 'text-xs' }"
+            @update:open="editor.chain().setMeta('lockDragHandle', $event).run()"
+          >
+            <UButton
+              color="neutral"
+              variant="ghost"
+              active-variant="soft"
+              size="sm"
+              :icon="appConfig.ui.icons.drag"
+              :active="open"
+              :class="ui.handle()"
+            />
+          </UDropdownMenu>
+        </UEditorDragHandle>
+      </UEditor>
+
+      <template #fallback>
+        <div class="p-4 sm:p-10 max-w-3xl mx-auto space-y-4">
+          <USkeleton class="h-8 w-2/3" />
+          <USkeleton class="h-4 w-full" />
+          <USkeleton class="h-4 w-5/6" />
+          <USkeleton class="h-4 w-3/4" />
+        </div>
+      </template>
+    </ClientOnly>
+  </div>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioViewLanding.vue b/docs/app/components/theme-studio/ThemeStudioViewLanding.vue
new file mode 100644
index 0000000000..efa153b135
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioViewLanding.vue
@@ -0,0 +1,492 @@
+<script setup lang="ts">
+import type { NavigationMenuItem } from '@nuxt/ui'
+
+const appConfig = useAppConfig()
+const extra = useStudioExtraIcons()
+
+/** Shared rhythm for the centered content sections. */
+const sectionUi = {
+  root: 'py-24 sm:py-32',
+  container: 'max-w-5xl',
+  headline: 'text-center font-mono font-medium text-xs text-primary uppercase tracking-[0.12em]',
+  title: 'max-w-lg mx-auto',
+  description: 'max-w-md mx-auto text-dimmed'
+}
+
+const navItems: NavigationMenuItem[] = [
+  { label: 'Features' },
+  { label: 'Metrics' }
+]
+
+type TerminalSegment = {
+  text: string
+  class?: string
+}
+
+const terminalLines: TerminalSegment[][] = [
+  [
+    { text: '$ ', class: 'text-muted' },
+    { text: 'npx telemetry', class: 'text-highlighted' },
+    { text: ' init', class: 'text-primary' }
+  ],
+  [{ text: '→ Scanning service topology...', class: 'text-muted' }],
+  [
+    { text: '→ Found ', class: 'text-muted' },
+    { text: '23 services', class: 'text-highlighted' },
+    { text: ', ', class: 'text-muted' },
+    { text: '847 endpoints', class: 'text-highlighted' },
+    { text: ', ', class: 'text-muted' },
+    { text: '12 databases', class: 'text-highlighted' }
+  ],
+  [
+    { text: '→ Deploying collector agents ', class: 'text-muted' },
+    { text: '✓', class: 'text-success' }
+  ],
+  [
+    { text: '→ Baseline established in ', class: 'text-muted' },
+    { text: '340ms', class: 'text-primary' }
+  ],
+  [{ text: ' ' }],
+  [
+    { text: '✓ Live at ', class: 'text-success' },
+    { text: 'https://app.example.com/acme-corp', class: 'text-info' }
+  ]
+]
+
+const logos = [
+  'i-simple-icons-vercel',
+  extra.github,
+  'i-simple-icons-linear',
+  'i-simple-icons-supabase',
+  'i-simple-icons-stripe'
+]
+
+const features = [{
+  icon: extra.zap,
+  title: 'Predictive Alerts',
+  description: 'ML models trained on your baselines detect anomalies 4 minutes before they hit your SLOs.'
+}, {
+  icon: 'i-lucide-radar',
+  title: 'Topology Mapping',
+  description: 'Auto-discovers service dependencies with zero config. See how a deploy in auth-service ripples through checkout.'
+}, {
+  icon: 'i-lucide-layers',
+  title: 'Unified Telemetry',
+  description: 'Logs, metrics, and traces in one query language. Stop context-switching. Start correlating.'
+}, {
+  icon: 'i-lucide-git-commit-horizontal',
+  title: 'Deploy Tracking',
+  description: 'Every deploy is automatically correlated with performance changes. Know which commit caused the regression.'
+}, {
+  icon: extra.filter,
+  title: 'Smart Sampling',
+  description: 'AI-driven sampling retains interesting traces and drops noise. Cut storage costs 10× without losing signal.'
+}, {
+  icon: 'i-lucide-notebook-pen',
+  title: 'Team Notebooks',
+  description: 'Collaborative investigation notebooks that turn incident debugging into reusable runbooks.'
+}]
+
+const metrics = [
+  { value: '99.99%', label: 'Uptime SLA', class: 'text-success' },
+  { value: '<50ms', label: 'P99 query', class: 'text-primary' },
+  { value: '14B+', label: 'Events / day', class: 'text-info' },
+  { value: '4 min', label: 'Early warning', class: 'text-warning' }
+]
+
+const footerLinks = ['Docs', 'GitHub', 'Twitter', 'Status', 'Privacy']
+
+const { copy: copyCommand, copied } = useClipboard()
+
+/** Fade-and-rise elements into view on scroll, like the template's `whileInView` motion. */
+const vReveal = {
+  mounted(el: HTMLElement & { _reveal?: IntersectionObserver }, binding: { value?: number }) {
+    el.classList.add('landing-reveal')
+    if (binding.value) {
+      el.style.transitionDelay = `${binding.value}ms`
+    }
+
+    el._reveal = new IntersectionObserver(([entry]) => {
+      if (entry?.isIntersecting) {
+        el.classList.add('landing-revealed')
+        el._reveal?.disconnect()
+      }
+    }, { threshold: 0.3 })
+    el._reveal.observe(el)
+  },
+  // below-the-fold elements never intersect when the user switches views,
+  // without this their observers outlive the DOM
+  unmounted(el: HTMLElement & { _reveal?: IntersectionObserver }) {
+    el._reveal?.disconnect()
+  }
+}
+</script>
+
+<template>
+  <div class="h-full overflow-y-auto bg-default">
+    <!-- Header -->
+    <header class="sticky top-0 z-10 border-b border-default bg-default/75 backdrop-blur rounded-t-[inherit]">
+      <div class="flex h-14 items-center justify-between gap-3 px-4 sm:px-6">
+        <div class="flex items-center gap-1.5 sm:flex-1">
+          <UIcon name="i-lucide-activity" class="size-5 text-primary shrink-0" />
+          <span class="text-base font-bold text-highlighted">Telemetry</span>
+        </div>
+
+        <UNavigationMenu :items="navItems" variant="link" class="hidden sm:flex" />
+
+        <div class="flex items-center justify-end gap-1.5 sm:flex-1">
+          <UButton label="Sign in" color="neutral" variant="ghost" class="hidden sm:inline-flex" />
+          <UButton label="Get started" color="neutral" />
+        </div>
+      </div>
+    </header>
+
+    <!-- Hero -->
+    <UPageHero
+      :ui="{
+        container: 'relative z-10 py-16 sm:py-24 lg:py-32 gap-12 sm:gap-16',
+        wrapper: 'flex flex-col items-center',
+        title: 'sm:text-6xl lg:text-7xl tracking-tighter leading-[1.05]',
+        description: 'mt-5 max-w-xl mx-auto text-base sm:text-lg leading-relaxed text-default',
+        links: 'gap-3'
+      }"
+    >
+      <template #top>
+        <div class="landing-pixels absolute inset-x-0 top-0 h-full opacity-15" aria-hidden="true" />
+        <div class="landing-glow absolute top-0 left-1/2 h-1/2 w-2/3 -translate-x-1/2" aria-hidden="true" />
+      </template>
+
+      <template #headline>
+        <div class="landing-enter" style="animation-delay: 200ms">
+          <UBadge
+            label="v2.0, Now with predictive alerting"
+            color="neutral"
+            variant="soft"
+            class="rounded-full px-3 py-1.5 gap-1.5 bg-inverted/5 backdrop-blur"
+          >
+            <template #leading>
+              <UChip inset standalone :ui="{ base: 'animate-pulse ring-0' }" />
+            </template>
+          </UBadge>
+        </div>
+      </template>
+
+      <template #title>
+        <span class="landing-enter inline-block" style="animation-delay: 350ms">
+          Observe less.
+          <br>
+          <span class="landing-shimmer bg-clip-text text-transparent">Understand more.</span>
+        </span>
+      </template>
+
+      <template #description>
+        <span class="landing-enter inline-block" style="animation-delay: 500ms">
+          Map your entire system in real-time, surface anomalies before they cascade, and eliminate the dashboards you never needed.
+        </span>
+      </template>
+
+      <template #links>
+        <div class="landing-enter flex flex-wrap justify-center gap-3" style="animation-delay: 650ms">
+          <UButton label="Start for free" variant="solid" size="xl" class="landing-btn-glow" />
+          <UButton label="View demo" color="neutral" variant="soft" size="xl" />
+        </div>
+      </template>
+
+      <div class="landing-enter max-w-2xl mx-auto w-full" style="animation-delay: 850ms">
+        <div class="rounded-xl border border-default bg-elevated/50 backdrop-blur overflow-hidden">
+          <div class="flex items-center gap-1.5 border-b border-default p-4 sm:px-6">
+            <span class="size-2.5 rounded-full border border-default bg-muted" />
+            <span class="size-2.5 rounded-full border border-default bg-muted" />
+            <span class="size-2.5 rounded-full border border-default bg-muted" />
+          </div>
+
+          <div class="min-h-[200px] p-5 sm:p-6 font-mono text-[13px] leading-[1.8] text-start">
+            <p
+              v-for="(line, index) in terminalLines"
+              :key="index"
+              class="landing-terminal-line truncate"
+              :style="{ animationDelay: `${1400 + index * 400}ms` }"
+            >
+              <span v-for="(segment, segmentIndex) in line" :key="segmentIndex" :class="segment.class">{{ segment.text }}</span>
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <div class="landing-enter max-w-lg mx-auto w-full" style="animation-delay: 950ms">
+        <UPageLogos
+          title="Trusted by engineering teams at"
+          :items="logos"
+          :ui="{
+            title: 'font-mono uppercase text-xs tracking-[0.12em] text-dimmed',
+            logo: 'text-muted size-6'
+          }"
+        />
+      </div>
+    </UPageHero>
+
+    <!-- Features -->
+    <UPageSection
+      :ui="sectionUi"
+    >
+      <template #headline>
+        <span v-reveal class="inline-block">Capabilities</span>
+      </template>
+
+      <template #title>
+        <span v-reveal="100" class="inline-block">Every signal, one surface.</span>
+      </template>
+
+      <template #description>
+        <span v-reveal="200" class="inline-block">No more tab-switching between metrics, traces, and logs. Correlate everything into a single explorable topology.</span>
+      </template>
+
+      <div class="rounded-2xl border border-default bg-default overflow-hidden">
+        <div class="grid grid-cols-1 sm:grid-cols-2 xl:grid-cols-3 gap-px">
+          <UPageCard
+            v-for="(feature, index) in features"
+            :key="feature.title"
+            v-reveal="index * 80"
+            :icon="feature.icon"
+            :title="feature.title"
+            :description="feature.description"
+            class="rounded-none duration-300 hover:bg-elevated/50"
+            :ui="{
+              leading: 'mb-5 flex size-9 items-center justify-center rounded-lg bg-primary/10',
+              title: 'text-sm tracking-tight',
+              description: 'text-sm leading-relaxed text-dimmed'
+            }"
+          />
+        </div>
+      </div>
+    </UPageSection>
+
+    <!-- Metrics -->
+    <UPageSection
+      :ui="sectionUi"
+    >
+      <template #headline>
+        <span v-reveal class="inline-block">By the numbers</span>
+      </template>
+
+      <template #title>
+        <span v-reveal="100" class="inline-block">Built for scale you haven't hit yet.</span>
+      </template>
+
+      <template #description>
+        <span v-reveal="200" class="inline-block">Process billions of events per day across thousands of production environments with an architecture designed for the workloads of 2030.</span>
+      </template>
+
+      <div class="rounded-2xl border border-default bg-default overflow-hidden">
+        <div class="grid grid-cols-2 xl:grid-cols-4 gap-px">
+          <UPageCard
+            v-for="(metric, index) in metrics"
+            :key="metric.label"
+            v-reveal="index * 80"
+            :title="metric.value"
+            :description="metric.label"
+            class="rounded-none duration-300 hover:bg-elevated/50"
+            :ui="{
+              root: 'text-center',
+              wrapper: 'items-center',
+              title: ['text-3xl sm:text-4xl font-bold tracking-tight leading-none', metric.class],
+              description: 'font-mono text-xs uppercase tracking-[0.06em] text-dimmed mt-3'
+            }"
+          />
+        </div>
+      </div>
+    </UPageSection>
+
+    <!-- CTA -->
+    <UPageCTA
+      variant="naked"
+      :ui="{
+        root: 'py-24 sm:py-32',
+        container: 'max-w-3xl text-center',
+        title: 'lg:text-5xl tracking-tighter',
+        description: 'mx-auto max-w-sm leading-relaxed text-dimmed'
+      }"
+    >
+      <template #top>
+        <div class="landing-glow absolute bottom-0 left-1/2 h-1/2 w-2/3 -translate-x-1/2" aria-hidden="true" />
+      </template>
+
+      <template #title>
+        <span v-reveal class="inline-block">Ready to stop<br>firefighting?</span>
+      </template>
+
+      <template #description>
+        <span v-reveal="100" class="inline-block">Free for up to 5 services. No credit card. Deploys in under a minute.</span>
+      </template>
+
+      <template #links>
+        <div v-reveal="200" class="flex flex-col items-center justify-center gap-6">
+          <UButton label="Start for free" variant="solid" size="xl" class="landing-btn-glow" />
+
+          <UButton
+            label="npx telemetry init"
+            :trailing-icon="copied ? appConfig.ui.icons.copyCheck : appConfig.ui.icons.copy"
+            color="neutral"
+            variant="subtle"
+            size="xl"
+            class="font-mono font-light text-toned gap-4"
+            :ui="{ trailingIcon: 'size-5' }"
+            @click="copyCommand('npx telemetry init')"
+          />
+        </div>
+      </template>
+    </UPageCTA>
+
+    <!-- Footer -->
+    <UFooter :ui="{ container: 'border-t border-default lg:py-8', right: 'gap-x-0 flex-wrap justify-end' }">
+      <template #left>
+        <p class="text-sm text-dimmed">
+          Built with Nuxt UI • © 2026
+        </p>
+      </template>
+
+      <template #right>
+        <UButton
+          v-for="link in footerLinks"
+          :key="link"
+          :label="link"
+          color="neutral"
+          variant="link"
+          size="sm"
+          class="font-light"
+        />
+      </template>
+    </UFooter>
+  </div>
+</template>
+
+<style scoped>
+/* Pixelated plasma backdrop, CSS stand-in for the template's HeroShaders (Plasma + Pixelate). */
+.landing-pixels {
+  pointer-events: none;
+  background-image:
+    radial-gradient(ellipse 80% 55% at 50% 0%, var(--ui-primary), transparent 70%),
+    radial-gradient(ellipse 45% 45% at 12% 18%, var(--ui-primary), transparent 70%),
+    radial-gradient(ellipse 45% 45% at 88% 28%, var(--ui-primary), transparent 70%);
+  mask-image:
+    repeating-linear-gradient(0deg, black 0 9px, transparent 9px 13px),
+    repeating-linear-gradient(90deg, black 0 9px, transparent 9px 13px),
+    linear-gradient(to bottom, black 20%, transparent 95%);
+  mask-composite: intersect;
+  animation: landing-plasma 16s ease-in-out infinite alternate;
+}
+
+@keyframes landing-plasma {
+  0% {
+    background-position: 0 0, 0 0, 0 0;
+  }
+  100% {
+    background-position: 0 2rem, 3rem 1rem, -3rem 2rem;
+  }
+}
+
+/* Radial primary glow, port of the template's GradientGlow component. */
+.landing-glow {
+  pointer-events: none;
+  background: radial-gradient(ellipse at center, color-mix(in oklch, var(--ui-primary) 6%, transparent) 0%, transparent 70%);
+}
+
+/* Shimmering gradient text on the hero title's second line: primary against a
+   lighter shade of itself. Mixed off --ui-primary rather than ramp stops:
+   black-as-primary has no ramp, and the stops keep painting the last palette.
+   Dark mixes toward black instead, where the primary may itself be white. */
+.landing-shimmer {
+  background-image: linear-gradient(135deg, var(--ui-primary), color-mix(in oklch, var(--ui-primary) 65%, black), var(--ui-primary), color-mix(in oklch, var(--ui-primary) 65%, black), var(--ui-primary));
+  background-size: 200% auto;
+  animation: landing-shimmer 10s ease-in-out infinite alternate;
+}
+
+.dark .landing-shimmer {
+  background-image: linear-gradient(135deg, var(--ui-primary), color-mix(in oklch, var(--ui-primary) 65%, white), var(--ui-primary), color-mix(in oklch, var(--ui-primary) 65%, white), var(--ui-primary));
+}
+
+@keyframes landing-shimmer {
+  0% {
+    background-position: 0% center;
+  }
+  100% {
+    background-position: 200% center;
+  }
+}
+
+/* Glowing primary buttons, port of the template's app.config button compoundVariant. */
+.landing-btn-glow {
+  box-shadow: 0 0 20px color-mix(in oklch, var(--ui-primary) 25%, transparent);
+  transition: all 0.2s;
+}
+
+.landing-btn-glow:hover {
+  box-shadow: 0 0 30px color-mix(in oklch, var(--ui-primary) 35%, transparent);
+  transform: translateY(-1px);
+}
+
+.landing-btn-glow:active {
+  transform: translateY(0);
+}
+
+/* Hero entrance, port of the template's enter motion (fade + rise, staggered). */
+.landing-enter {
+  /* backwards, not both: a retained transform (even identity) would form a
+     backdrop root and blind children's backdrop-blur after the entrance */
+  animation: landing-enter 0.6s ease backwards;
+}
+
+@keyframes landing-enter {
+  from {
+    opacity: 0;
+    transform: translateY(16px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+/* Terminal lines type in one at a time. */
+.landing-terminal-line {
+  animation: landing-terminal-line 0.4s ease both;
+}
+
+@keyframes landing-terminal-line {
+  from {
+    opacity: 0;
+    transform: translateX(-4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+/* Scroll reveal, classes applied by the v-reveal directive. */
+.landing-reveal {
+  opacity: 0;
+  transform: translateY(16px);
+  transition: opacity 0.6s ease, transform 0.6s ease;
+}
+
+.landing-reveal.landing-revealed {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .landing-pixels,
+  .landing-shimmer,
+  .landing-enter,
+  .landing-terminal-line {
+    animation: none;
+  }
+
+  .landing-reveal {
+    opacity: 1;
+    transform: none;
+    transition: none;
+  }
+}
+</style>
diff --git a/docs/app/components/theme-studio/ThemeStudioViewPortfolio.vue b/docs/app/components/theme-studio/ThemeStudioViewPortfolio.vue
new file mode 100644
index 0000000000..bf65c4502c
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioViewPortfolio.vue
@@ -0,0 +1,379 @@
+<script setup lang="ts">
+import type { NavigationMenuItem } from '@nuxt/ui'
+
+const appConfig = useAppConfig()
+const extra = useStudioExtraIcons()
+
+// Replicates the Nuxt UI Portfolio template home page: floating pill nav,
+// avatar hero with polaroid marquee, about + work experience columns,
+// blog list, testimonial carousel, FAQ tabs and footer.
+const navItems: NavigationMenuItem[] = [
+  { label: 'Home', icon: extra.home, active: true },
+  { label: 'Projects', icon: appConfig.ui.icons.folder },
+  { label: 'Blog', icon: appConfig.ui.icons.file },
+  { label: 'Speaking', icon: extra.mic },
+  { label: 'About', icon: extra.user }
+]
+
+const socialLinks = [
+  { 'icon': 'i-simple-icons-discord', 'aria-label': 'Discord' },
+  { 'icon': 'i-simple-icons-x', 'aria-label': 'X' },
+  { 'icon': extra.github, 'aria-label': 'GitHub' }
+]
+
+// The template scrolls travel photos in a marquee; we stand in gradient
+// polaroids since the studio previews stay image-free.
+const heroImages = [
+  { icon: 'i-lucide-mountain', label: 'Alps, 2024' },
+  { icon: extra.coffee, label: 'Café sketching' },
+  { icon: 'i-lucide-bike', label: 'Canal ride' },
+  { icon: extra.camera, label: 'Street photos' },
+  { icon: 'i-lucide-laptop', label: 'Studio desk' },
+  { icon: 'i-lucide-trees', label: 'Veluwe hike' },
+  { icon: extra.palette, label: 'Color studies' },
+  { icon: 'i-lucide-ferris-wheel', label: 'Rotterdam fair' },
+  { icon: 'i-lucide-waves', label: 'North Sea' }
+]
+
+const about = {
+  title: 'About Me',
+  // \n renders as a real break via whitespace-pre-line on the description slot
+  description: 'I\'m an English designer and developer based in Amsterdam. I sit right between design and engineering, which means both teams assume I\'m the other team\'s problem.'
+}
+
+const experience = [{
+  date: '2025 - Present',
+  position: 'Public Contributor for',
+  company: { name: 'Nuxt UI', logo: 'i-simple-icons-nuxtdotjs' }
+}, {
+  date: '2024 - Present',
+  position: 'Founder of',
+  company: { name: 'Lovd', logo: 'material-symbols:bookmark-heart' }
+}, {
+  date: '2019 - 2021',
+  position: 'Web Developer at',
+  company: { name: 'Blender', logo: 'i-simple-icons-blender' }
+}, {
+  date: '1995 - Present',
+  position: 'Human person on',
+  company: { name: 'Earth', logo: extra.globe }
+}]
+
+const posts = [{
+  title: 'Twelve Identical Greys: A Field Guide to Choosing Your Neutral',
+  description: 'They are not identical and I will die on this hill. Slate is cool, stone is warm, zinc is for when you can\'t commit - a practical taxonomy.',
+  date: 'Apr 23, 2025'
+}, {
+  title: 'I Nudged a Border Radius by 0.125rem and Felt Something',
+  description: 'A meditation on the space between rounded-md and rounded-lg, and why nobody else at the review could see the difference. They saw it. They\'re being polite.',
+  date: 'Mar 15, 2025'
+}, {
+  title: 'My Design System Now Has Its Own Design System',
+  description: 'The tokens have tokens. The naming convention has a naming convention. At some point I will ship a button - a retrospective.',
+  date: 'Mar 5, 2025'
+}]
+
+// Obviously-fake reviews: the testimonial carousel demos better with famous
+// dead Dutch masters than with invented product directors.
+const testimonials = [{
+  quote: 'At last, a man who treats the grid as a moral position. I did notice his palette editor permits more than three colors, I have chosen to forgive this.',
+  author: { name: 'Piet Mondrian', description: 'Painter & grid enthusiast, 1872–1944' }
+}, {
+  quote: 'I asked for a simple staircase component. The popovers opened into popovers, which opened into further popovers. Honestly, I have never felt more at home.',
+  author: { name: 'M.C. Escher', description: 'Staircase guy, 1898–1972' }
+}, {
+  quote: 'I set the primary color to chrome yellow and wept at the shades it produced. Five stars. Would have commissioned him, but our schedules never aligned.',
+  author: { name: 'Vincent van Gogh', description: 'Colorist, freelance, 1853–1890' }
+}]
+
+const faqCategories = [{
+  label: 'Services & Process',
+  questions: [{
+    label: 'What services do you offer?',
+    content: 'Design systems, UX/UI design and front-end development - designed in Figma, built in Nuxt. I also cover the surrounding craft: branding, print, photography, video and animation.'
+  }, {
+    label: 'What is your design process like?',
+    content: 'Iterative: sketch, build, squint at it in dark mode, nudge a slider by 0.125rem, declare it the final tweak. Repeat until shipped, or until someone gently takes the slider away.'
+  }, {
+    label: 'Do you work with startups?',
+    content: 'Absolutely - I run one. The daily standup is me and a wall of post-it notes, and the post-its are consistently flaking.'
+  }]
+}, {
+  label: 'Pricing & Timelines',
+  questions: [{
+    label: 'How much does a project typically cost?',
+    content: 'This theme editor is free and takes payment in GitHub stars. For anything else: it depends - an answer that has never once been wrong.'
+  }, {
+    label: 'What are your payment terms?',
+    content: 'Stroopwafels, baked beans, or sincere compliments about my border-radius choices. Bank transfer is also, grudgingly, accepted.'
+  }, {
+    label: 'How long does a typical project take?',
+    content: 'Somewhere between one focused afternoon and "I rebuilt the design system twice, it\'s better now, please don\'t ask." Discovery narrows this down considerably.'
+  }]
+}, {
+  label: 'About Me',
+  questions: [{
+    label: 'What do you enjoy most about your work?',
+    content: 'Watching someone use a thing I built and say "oh, I found a bug". Bridging user needs and technical constraints is the puzzle that keeps me here while the users scare me away.'
+  }, {
+    label: 'What are your hobbies outside of work?',
+    content: 'Arts and crafts, film photography, hunting down good curry in Amsterdam and contributing to open-source UI tooling.'
+  }]
+}]
+
+// Template's Motion blur-in on the hero, replayed as staggered CSS transitions.
+const heroAppear = ref(false)
+let appearTimeout: ReturnType<typeof setTimeout> | undefined
+onMounted(() => {
+  appearTimeout = setTimeout(() => {
+    heroAppear.value = true
+  }, 0)
+})
+onUnmounted(() => clearTimeout(appearTimeout))
+</script>
+
+<template>
+  <!-- A mini portfolio: the pane is the scroll container, so the pill nav sticks to it. -->
+  <div class="h-full overflow-y-auto bg-default">
+    <!-- Template's AppHeader: a floating centered pill navigation. -->
+    <div class="sticky top-2 sm:top-4 z-10 flex justify-center pointer-events-none">
+      <UNavigationMenu
+        :items="navItems"
+        variant="link"
+        color="neutral"
+        class="pointer-events-auto bg-muted/80 backdrop-blur-sm rounded-full px-2 sm:px-4 border border-muted/50 shadow-lg shadow-neutral-950/5"
+        :ui="{
+          link: 'px-2 py-1',
+          linkLeadingIcon: 'hidden'
+        }"
+      >
+        <template #list-trailing>
+          <UButton
+            icon="i-lucide-sun-moon"
+            aria-label="Color mode"
+            color="neutral"
+            variant="ghost"
+            size="sm"
+          />
+        </template>
+      </UNavigationMenu>
+    </div>
+
+    <UContainer class="max-w-4xl sm:border-x border-default -mt-12 pt-10">
+      <UPageHero
+        title="Hey, I'm Mike Newbon Design Engineer"
+        description="Based in Amsterdam, I craft intuitive digital products, where design meets fun-ctionality. Like this theme editor!"
+        :ui="{
+          container: 'py-18 sm:py-24 lg:py-32',
+          headline: 'flex items-center justify-center',
+          title: 'text-shadow-md max-w-lg mx-auto text-balance text-3xl sm:text-4xl lg:text-5xl',
+          description: 'mt-2 text-md mx-auto max-w-2xl text-balance sm:text-md text-muted',
+          links: 'mt-4 flex-col justify-center items-center'
+        }"
+      >
+        <template #headline>
+          <UAvatar
+            alt="Mike Newbon"
+            size="3xl"
+            src="https://github.com/mikenewbon.png"
+            class="size-18 ring ring-default ring-offset-3 ring-offset-bg transition-all duration-600"
+            :class="heroAppear ? 'opacity-100 blur-none scale-100' : 'opacity-0 blur-lg scale-110'"
+          />
+        </template>
+
+        <template #links>
+          <div class="flex items-center gap-2">
+            <UButton :icon="extra.github" label="View Github" color="neutral" to="https://github.com/mikenewbon/" target="_blank" />
+            <UButton color="success" variant="ghost" class="gap-2" label="Always online">
+              <template #leading>
+                <span class="relative flex size-2">
+                  <span class="absolute inline-flex size-full rounded-full opacity-75 bg-success animate-ping" />
+                  <span class="relative inline-flex size-2 scale-90 rounded-full bg-success" />
+                </span>
+              </template>
+            </UButton>
+          </div>
+
+          <div class="gap-x-4 inline-flex mt-4">
+            <UButton
+              v-for="(link, index) of socialLinks"
+              :key="index"
+              v-bind="{ size: 'md', color: 'neutral', variant: 'ghost', ...link }"
+            />
+          </div>
+        </template>
+
+        <UMarquee pause-on-hover class="py-2 -mx-8 sm:-mx-12 lg:-mx-16 [--duration:40s]">
+          <div
+            v-for="(img, index) in heroImages"
+            :key="index"
+            class="w-[234px] aspect-square shrink-0 rounded-lg overflow-hidden relative bg-elevated flex flex-col items-center justify-center gap-3"
+            :class="index % 2 === 0 ? '-rotate-2' : 'rotate-2'"
+          >
+            <div
+              class="absolute inset-0"
+              :style="{ background: `radial-gradient(ellipse at ${index % 2 === 0 ? '30% 20%' : '70% 80%'}, color-mix(in srgb, var(--ui-primary) ${12 + (index % 3) * 6}%, transparent), transparent 70%)` }"
+            />
+            <UIcon :name="img.icon" class="size-10 text-dimmed relative" />
+            <span class="text-xs text-muted font-medium relative">{{ img.label }}</span>
+          </div>
+        </UMarquee>
+      </UPageHero>
+
+      <!-- About + work experience share a two-column section on the template home. -->
+      <UPageSection :ui="{ container: 'pt-0! lg:grid lg:grid-cols-2 lg:gap-8' }">
+        <UPageSection
+          :title="about.title"
+          :description="about.description"
+          :ui="{
+            container: 'p-0!',
+            title: 'text-left text-xl sm:text-xl lg:text-2xl font-medium',
+            description: 'text-left mt-3 text-sm sm:text-md lg:text-sm text-muted whitespace-pre-line'
+          }"
+        />
+
+        <UPageSection
+          title="Work Experience"
+          :ui="{
+            container: 'p-0! gap-4 sm:gap-4',
+            title: 'text-left text-xl sm:text-xl lg:text-2xl font-medium',
+            description: 'mt-2'
+          }"
+        >
+          <template #description>
+            <div class="flex flex-col gap-2">
+              <div
+                v-for="(item, index) in experience"
+                :key="index"
+                class="text-muted flex items-center text-nowrap gap-2"
+              >
+                <p class="text-sm">
+                  {{ item.date }}
+                </p>
+                <USeparator />
+                <span class="flex items-center gap-1">
+                  <span class="text-sm">{{ item.position }}</span>
+                  <span class="inline-flex items-center gap-1 text-highlighted">
+                    <span class="font-medium text-sm">{{ item.company.name }}</span>
+                    <UIcon :name="item.company.logo" />
+                  </span>
+                </span>
+              </div>
+            </div>
+          </template>
+        </UPageSection>
+      </UPageSection>
+
+      <UPageSection
+        title="Latest Articles"
+        description="Some of my recent thoughts"
+        :ui="{
+          container: 'px-0 pt-0! sm:gap-6 lg:gap-8',
+          title: 'text-left text-xl sm:text-xl lg:text-2xl font-medium',
+          description: 'text-left mt-2 text-sm sm:text-md lg:text-sm text-muted'
+        }"
+      >
+        <UBlogPosts orientation="vertical" class="gap-4 lg:gap-y-4">
+          <UBlogPost
+            v-for="(post, index) in posts"
+            :key="index"
+            orientation="horizontal"
+            variant="naked"
+            v-bind="post"
+            to="#"
+            :ui="{
+              root: 'group relative lg:items-start lg:flex ring-0 hover:ring-0',
+              body: 'px-0!',
+              header: 'hidden'
+            }"
+          >
+            <template #footer>
+              <UButton size="xs" variant="link" class="px-0 gap-0" label="Read Article">
+                <template #trailing>
+                  <UIcon
+                    :name="appConfig.ui.icons.arrowRight"
+                    class="size-4 text-primary transition-all opacity-0 group-hover:translate-x-1 group-hover:opacity-100"
+                  />
+                </template>
+              </UButton>
+            </template>
+          </UBlogPost>
+        </UBlogPosts>
+      </UPageSection>
+
+      <UPageSection :ui="{ container: 'px-0 pt-0!' }">
+        <UCarousel
+          v-slot="{ item }"
+          :items="testimonials"
+          :autoplay="{ delay: 4000 }"
+          loop
+          dots
+          :ui="{ viewport: '-mx-4 sm:-mx-12 lg:-mx-16 bg-elevated/50 max-w-(--ui-container)' }"
+        >
+          <UPageCTA
+            :description="item.quote"
+            variant="naked"
+            class="rounded-none"
+            :ui="{
+              container: 'sm:py-12 lg:py-12 sm:gap-8',
+              description: 'text-base! text-balance before:content-[open-quote] before:text-5xl lg:before:text-7xl before:inline-block before:text-dimmed before:absolute before:-ml-6 lg:before:-ml-10 before:-mt-2 lg:before:-mt-4 after:content-[close-quote] after:text-5xl lg:after:text-7xl after:inline-block after:text-dimmed after:absolute after:mt-1 lg:after:mt-0 after:ml-1 lg:after:ml-2'
+            }"
+          >
+            <UUser
+              v-bind="item.author"
+              :avatar="{ alt: item.author.name }"
+              size="xl"
+              class="justify-center"
+            />
+          </UPageCTA>
+        </UCarousel>
+      </UPageSection>
+
+      <UPageSection
+        title="Frequently Asked Questions"
+        description="Answers to common questions about my process and services."
+        :ui="{
+          container: 'px-0 pt-0! gap-4 sm:gap-4',
+          title: 'text-left text-xl sm:text-xl lg:text-2xl font-medium',
+          description: 'text-left mt-2 text-sm sm:text-md lg:text-sm text-muted'
+        }"
+      >
+        <UTabs
+          :items="faqCategories"
+          orientation="horizontal"
+          :ui="{
+
+          }"
+        >
+          <template #content="{ item }">
+            <UAccordion
+              :trailing-icon="appConfig.ui.icons.plus"
+              :items="item.questions"
+              :unmount-on-hide="false"
+              :ui="{
+                item: 'border-none',
+                trigger: 'mb-2 border-0 group px-4 transform-gpu rounded-lg bg-elevated/60 will-change-transform hover:bg-muted/50 text-base',
+                body: 'px-4',
+                trailingIcon: 'group-data-[state=closed]:rotate-0 group-data-[state=open]:rotate-135 text-base text-muted'
+              }"
+            />
+          </template>
+        </UTabs>
+      </UPageSection>
+
+      <UFooter class="z-10 bg-default" :ui="{ left: 'text-muted text-xs' }">
+        <template #left>
+          Built with Nuxt UI • © 2026
+        </template>
+
+        <template #right>
+          <UButton
+            v-for="(link, index) of socialLinks"
+            :key="index"
+            v-bind="{ size: 'xs', color: 'neutral', variant: 'ghost', ...link }"
+          />
+        </template>
+      </UFooter>
+    </UContainer>
+  </div>
+</template>
diff --git a/docs/app/components/theme-studio/ThemeStudioViewSaas.vue b/docs/app/components/theme-studio/ThemeStudioViewSaas.vue
new file mode 100644
index 0000000000..039e2c0373
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioViewSaas.vue
@@ -0,0 +1,501 @@
+<script setup lang="ts">
+import type { NavigationMenuItem } from '@nuxt/ui'
+
+const appConfig = useAppConfig()
+const extra = useStudioExtraIcons()
+
+const navItems: NavigationMenuItem[] = [
+  { label: 'Docs', active: true },
+  { label: 'Pricing' },
+  { label: 'Blog' },
+  { label: 'Changelog' }
+]
+
+const heroLinks = [{
+  label: 'Get started',
+  trailingIcon: appConfig.ui.icons.arrowRight,
+  size: 'xl' as const
+}, {
+  label: 'Use this template',
+  icon: extra.github,
+  size: 'xl' as const,
+  color: 'neutral' as const,
+  variant: 'subtle' as const
+}]
+
+const sections = [{
+  title: 'Powered by Nuxt UI components',
+  description: 'Access a complete component library with beautifully styled, accessible and customizable Vue components. Everything you need to build professional SaaS applications.',
+  reverse: false,
+  features: [{
+    title: '100+ UI components',
+    description: 'From buttons to modals, data tables to forms - all styled with Tailwind CSS and accessible out of the box.',
+    icon: extra.package
+  }, {
+    title: 'Authentication ready',
+    description: 'Pre-built login, signup and password reset flows. Just connect your backend and start onboarding users.',
+    icon: extra.shield
+  }, {
+    title: 'TypeScript first',
+    description: 'Full TypeScript support with auto-completion, type safety and IntelliSense for every component.',
+    icon: 'i-lucide-code-xml'
+  }]
+}, {
+  title: 'Built for modern SaaS',
+  description: 'Everything you need to launch and scale. From beautiful marketing pages to complex dashboards, ship faster with production-ready patterns.',
+  reverse: true,
+  features: [{
+    title: 'Edge performance',
+    description: 'Optimized for Core Web Vitals with automatic code splitting, lazy loading and SSR/SSG support.',
+    icon: extra.zap
+  }, {
+    title: 'Dark mode ready',
+    description: 'Automatic theme switching with smooth transitions. Respects system preferences and remembers user choice.',
+    icon: appConfig.ui.icons.dark
+  }, {
+    title: 'Global ready',
+    description: 'Built-in i18n support for 50+ languages with RTL/LTR layouts and font optimization.',
+    icon: extra.globe
+  }]
+}]
+
+const features = [{
+  title: 'Beautiful design system',
+  description: 'Semantic color aliases, comprehensive design tokens and Tailwind Variants for consistent styling.',
+  icon: extra.palette
+}, {
+  title: 'Accessible by default',
+  description: 'Built on Reka UI for robust accessibility. WCAG compliant components that work for everyone.',
+  icon: 'i-lucide-accessibility'
+}, {
+  title: 'Developer experience',
+  description: 'Auto-imports, hot module replacement and comprehensive documentation. Build faster with less friction.',
+  icon: extra.terminal
+}, {
+  title: 'SEO optimized',
+  description: 'Server-side rendering, automatic meta tags, sitemap generation and Open Graph images out of the box.',
+  icon: appConfig.ui.icons.search
+}, {
+  title: 'Production ready',
+  description: 'Error handling, loading states, form validation and security best practices built into every component.',
+  icon: appConfig.ui.icons.success
+}, {
+  title: 'Infinitely customizable',
+  description: 'Override any style with the ui prop, customize globally with AppConfig, or use Tailwind classes directly.',
+  icon: extra.settings
+}]
+
+const plans = [{
+  title: 'Basic',
+  description: 'A basic plan for individuals.',
+  price: '$9',
+  features: ['1 GB storage', '1 email account', '1 domain', 'Community support'],
+  button: { label: 'Get started', color: 'neutral' as const, variant: 'subtle' as const }
+}, {
+  title: 'Standard',
+  description: 'A standard plan for small teams.',
+  price: '$19',
+  highlight: true,
+  badge: 'Most popular',
+  features: ['10 GB storage', '10 email accounts', '10 domains', 'Priority support'],
+  button: { label: 'Get started' }
+}, {
+  title: 'Premium',
+  description: 'A premium plan for large teams.',
+  price: '$29',
+  features: ['100 GB storage', '100 email accounts', '100 domains', 'Dedicated support'],
+  button: { label: 'Get started', color: 'neutral' as const, variant: 'subtle' as const }
+}]
+
+const testimonials = [{
+  quote: 'Nuxt UI transformed how we build. The component quality is exceptional - everything just works with perfect TypeScript support, accessibility and dark mode built in.',
+  user: { name: 'Sarah Chen', description: 'CTO at TechScale' }
+}, {
+  quote: 'We shipped our MVP in 2 weeks instead of 2 months. The authentication flows and form components saved us countless hours of development time.',
+  user: { name: 'Marcus Rodriguez', description: 'VP of Engineering at DataFlow' }
+}, {
+  quote: 'The design system with AppConfig is brilliant. We maintain brand consistency across all our products while leveraging the full component library.',
+  user: { name: 'David Kumar', description: 'Security Director at SecureStack' }
+}, {
+  quote: 'Perfect Lighthouse scores out of the box. Our Core Web Vitals improved dramatically just by switching to Nuxt UI components.',
+  user: { name: 'Emily Zhang', description: 'Lead Architect at ScaleForce' }
+}, {
+  quote: 'The Tailwind Variants system makes customization so intuitive. We can override any component style while keeping the functionality intact.',
+  user: { name: 'James Wilson', description: 'DevOps Lead at CloudPro' }
+}, {
+  quote: 'From the SaaS template to production in days. The pre-built layouts, navigation and content structure accelerated our launch.',
+  user: { name: 'Lisa Patel', description: 'CEO at AutoScale' }
+}]
+
+const ctaLinks = [{
+  label: 'Start building',
+  trailingIcon: appConfig.ui.icons.arrowRight
+}, {
+  label: 'View on GitHub',
+  icon: extra.github,
+  variant: 'subtle' as const
+}]
+
+const footerColumns = [{
+  label: 'Resources',
+  children: [
+    { label: 'Help center' },
+    { label: 'Docs' },
+    { label: 'Roadmap' },
+    { label: 'Changelog' }
+  ]
+}, {
+  label: 'Features',
+  children: [
+    { label: 'Affiliates' },
+    { label: 'Portal' },
+    { label: 'Jobs' },
+    { label: 'Sponsors' }
+  ]
+}, {
+  label: 'Company',
+  children: [
+    { label: 'About' },
+    { label: 'Pricing' },
+    { label: 'Careers' },
+    { label: 'Blog' }
+  ]
+}]
+
+const email = ref('')
+
+// Hero background beam fades in on mount, like the template's HeroBackground.
+const heroAppear = ref(false)
+const heroAppeared = ref(false)
+
+// The zero delay pushes the class flip past first paint so the fade-in
+// transition actually runs.
+let appearTimeout: ReturnType<typeof setTimeout> | undefined
+onMounted(() => {
+  appearTimeout = setTimeout(() => {
+    heroAppear.value = true
+    appearTimeout = setTimeout(() => {
+      heroAppeared.value = true
+    }, 1000)
+  }, 0)
+})
+onUnmounted(() => clearTimeout(appearTimeout))
+
+// Rising stars behind the CTA, ported from the template's StarsBg.
+interface Star {
+  x: number
+  y: number
+  size: number
+}
+
+function generateStars(count: number): Star[] {
+  return Array.from({ length: count }, () => ({
+    x: Math.floor(Math.random() * 2000),
+    y: Math.floor(Math.random() * 2000),
+    size: Math.random() + 1
+  }))
+}
+
+const starLayers = [
+  { stars: generateStars(80), duration: 100, opacity: 1 },
+  { stars: generateStars(60), duration: 150, opacity: 0.75 },
+  { stars: generateStars(60), duration: 200, opacity: 0.5 }
+]
+</script>
+
+<template>
+  <!-- A mini landing page: the pane is the scroll container, so the header sticks to it. -->
+  <div class="h-full overflow-y-auto bg-default">
+    <UHeader :toggle="false" class="rounded-t-[inherit]">
+      <template #left>
+        <div class="flex items-center gap-1.5">
+          <UIcon name="i-lucide-rocket" class="size-6 text-primary shrink-0" />
+          <span class="text-xl font-bold text-highlighted">SaaS</span>
+        </div>
+      </template>
+
+      <UNavigationMenu :items="navItems" variant="link" />
+
+      <template #right>
+        <UButton icon="i-lucide-sun-moon" aria-label="Color mode" color="neutral" variant="ghost" />
+        <UButton label="Sign in" color="neutral" variant="outline" class="hidden lg:inline-flex" />
+        <UButton label="Sign up" color="neutral" :trailing-icon="appConfig.ui.icons.arrowRight" />
+      </template>
+    </UHeader>
+
+    <UPageHero
+      description="Build production-ready SaaS applications with powerful components, authentication flows and enterprise features."
+      :links="heroLinks"
+    >
+      <template #top>
+        <!-- Template's HeroBackground: a primary beam along the header with a fading glow. -->
+        <div
+          class="absolute w-full -top-px transition-all text-primary shrink-0 pointer-events-none"
+          :class="[
+            heroAppear ? '' : 'opacity-0',
+            heroAppeared ? 'duration-[400ms]' : 'duration-1000'
+          ]"
+        >
+          <svg viewBox="0 0 1440 181" fill="none" xmlns="http://www.w3.org/2000/svg">
+            <mask id="saas-hero-mask" fill="white">
+              <path d="M0 0H1440V181H0V0Z" />
+            </mask>
+            <path d="M0 0H1440V181H0V0Z" fill="url(#saas-hero-glow)" fill-opacity="0.22" />
+            <path d="M0 2H1440V-2H0V2Z" fill="url(#saas-hero-beam)" mask="url(#saas-hero-mask)" />
+            <defs>
+              <linearGradient
+                id="saas-hero-glow"
+                x1="720"
+                y1="0"
+                x2="720"
+                y2="181"
+                gradientUnits="userSpaceOnUse"
+              >
+                <stop stop-color="currentColor" />
+                <stop offset="1" stop-color="currentColor" stop-opacity="0" />
+              </linearGradient>
+              <linearGradient
+                id="saas-hero-beam"
+                x1="0"
+                y1="90.5"
+                x2="1440"
+                y2="90.5"
+                gradientUnits="userSpaceOnUse"
+              >
+                <stop stop-color="currentColor" stop-opacity="0" />
+                <stop offset="0.395" stop-color="currentColor" />
+                <stop offset="1" stop-color="currentColor" stop-opacity="0" />
+              </linearGradient>
+            </defs>
+          </svg>
+        </div>
+      </template>
+
+      <template #headline>
+        <UBadge variant="subtle" :icon="extra.sparkles">
+          Nuxt UI v4 is out
+        </UBadge>
+      </template>
+
+      <template #title>
+        Ship your <span class="text-primary">SaaS</span> at light speed
+      </template>
+
+      <!-- Template's PromotionalVideo: a framed media card below the hero copy. -->
+      <UPageCard variant="subtle" class="rounded-2xl">
+        <div class="relative aspect-video w-full rounded-xl overflow-hidden bg-elevated flex items-center justify-center">
+          <div class="absolute inset-0" style="background: radial-gradient(ellipse at 50% 0%, color-mix(in srgb, var(--ui-primary) 15%, transparent), transparent 70%)" />
+          <UButton
+            :icon="extra.play"
+            size="xl"
+            color="neutral"
+            variant="outline"
+            aria-label="Play video"
+            class="rounded-full"
+          />
+        </div>
+      </UPageCard>
+    </UPageHero>
+
+    <UPageSection
+      v-for="(section, index) in sections"
+      :key="index"
+      :title="section.title"
+      :description="section.description"
+      orientation="horizontal"
+      :reverse="section.reverse"
+      :features="section.features"
+    >
+      <!-- Template's ImagePlaceholder: a framed card with a diagonal-stripes pattern. -->
+      <UPageCard variant="subtle">
+        <div class="relative overflow-hidden rounded-sm border border-dashed border-accented opacity-75 px-4 flex items-center justify-center aspect-video">
+          <svg class="absolute inset-0 h-full w-full stroke-inverted/10" fill="none">
+            <defs>
+              <pattern
+                :id="`saas-stripes-${index}`"
+                x="0"
+                y="0"
+                width="10"
+                height="10"
+                patternUnits="userSpaceOnUse"
+              >
+                <path d="M-3 13 15-5M-5 5l18-18M-1 21 17 3" />
+              </pattern>
+            </defs>
+            <rect stroke="none" :fill="`url(#saas-stripes-${index})`" width="100%" height="100%" />
+          </svg>
+        </div>
+      </UPageCard>
+    </UPageSection>
+
+    <UPageSection
+      title="Everything you need to ship"
+      description="Stop building from scratch. Focus on your unique features while Nuxt UI handles the foundations with battle-tested components and patterns."
+    >
+      <UPageGrid>
+        <UPageCard
+          v-for="feature in features"
+          :key="feature.title"
+          v-bind="feature"
+          spotlight
+        />
+      </UPageGrid>
+    </UPageSection>
+
+    <UPageSection
+      title="A plan for every need"
+      description="Our plans are designed to meet the requirements of both individuals and teams. Get the right plan that suits you."
+    >
+      <UPricingPlans>
+        <UPricingPlan
+          v-for="plan in plans"
+          :key="plan.title"
+          v-bind="plan"
+          billing-cycle="/month"
+        />
+      </UPricingPlans>
+    </UPageSection>
+
+    <UPageSection
+      headline="Trusted by developers"
+      title="Join thousands building with Nuxt UI"
+      description="See why developers choose Nuxt UI to ship their SaaS applications faster and with more confidence."
+    >
+      <UPageColumns class="lg:columns-2 xl:columns-3">
+        <UPageCard
+          v-for="testimonial in testimonials"
+          :key="testimonial.user.name"
+          variant="subtle"
+          :description="testimonial.quote"
+          :ui="{ description: 'before:content-[open-quote] after:content-[close-quote]' }"
+        >
+          <template #footer>
+            <UUser
+              v-bind="testimonial.user"
+              :avatar="{ alt: testimonial.user.name }"
+              size="lg"
+            />
+          </template>
+        </UPageCard>
+      </UPageColumns>
+    </UPageSection>
+
+    <USeparator />
+
+    <UPageCTA
+      title="Ready to build an amazing SaaS?"
+      description="Join thousands of developers building with Nuxt and Nuxt UI. Get this template and start shipping today."
+      :links="ctaLinks"
+      variant="naked"
+      class="overflow-hidden"
+    >
+      <!-- Template's StarsBg: rising primary stars under a radial glow. -->
+      <div class="absolute pointer-events-none z-[-1] inset-y-0 inset-x-5 sm:inset-x-7 lg:inset-x-9 overflow-hidden">
+        <svg class="absolute inset-0 pointer-events-none size-full" viewBox="0 0 1017 181" fill="none" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="none">
+          <g opacity="0.5">
+            <path d="M0 0H1017V181H0V0Z" fill="url(#saas-stars-glow)" fill-opacity="0.22" />
+          </g>
+          <defs>
+            <radialGradient
+              id="saas-stars-glow"
+              cx="0"
+              cy="0"
+              r="1"
+              gradientUnits="userSpaceOnUse"
+              gradientTransform="translate(508.999 19.5) rotate(90.177) scale(161.501 509.002)"
+            >
+              <stop stop-color="var(--ui-primary)" />
+              <stop offset="1" stop-color="var(--ui-primary)" stop-opacity="0" />
+            </radialGradient>
+          </defs>
+        </svg>
+
+        <div class="stars size-full absolute inset-x-0 top-0">
+          <div
+            v-for="(layer, index) in starLayers"
+            :key="index"
+            class="star-layer"
+            :style="{
+              '--star-duration': `${layer.duration}s`,
+              '--star-opacity': layer.opacity
+            }"
+          >
+            <div
+              v-for="(star, starIndex) in layer.stars"
+              :key="starIndex"
+              class="absolute rounded-full bg-primary"
+              :style="{
+                left: `${star.x}px`,
+                top: `${star.y}px`,
+                width: `${star.size}px`,
+                height: `${star.size}px`,
+                opacity: 'var(--star-opacity)'
+              }"
+            />
+          </div>
+        </div>
+      </div>
+    </UPageCTA>
+
+    <USeparator icon="i-lucide-rocket" class="h-px" />
+
+    <UFooter :ui="{ top: 'border-b border-default' }">
+      <template #top>
+        <UContainer>
+          <UFooterColumns :columns="footerColumns">
+            <template #right>
+              <UFormField name="email" label="Subscribe to our newsletter" size="lg">
+                <UInput v-model="email" type="email" placeholder="Enter your email" class="w-full">
+                  <template #trailing>
+                    <UButton size="xs" color="neutral" label="Subscribe" />
+                  </template>
+                </UInput>
+              </UFormField>
+            </template>
+          </UFooterColumns>
+        </UContainer>
+      </template>
+
+      <template #left>
+        <p class="text-muted text-sm">
+          Built with Nuxt UI • © 2026
+        </p>
+      </template>
+
+      <template #right>
+        <UButton :icon="extra.github" aria-label="GitHub" color="neutral" variant="ghost" />
+        <UButton icon="i-lucide-twitter" aria-label="X" color="neutral" variant="ghost" />
+      </template>
+    </UFooter>
+  </div>
+</template>
+
+<style scoped>
+.stars {
+  left: 50%;
+  transform: translate(-50%);
+  mask-image: linear-gradient(180deg,
+      rgba(217, 217, 217, 0) 0%,
+      rgba(217, 217, 217, 0.8) 25%,
+      #d9d9d9 50%,
+      rgba(217, 217, 217, 0.8) 75%,
+      rgba(217, 217, 217, 0) 100%);
+  mask-size: cover;
+}
+
+.star-layer {
+  animation: risingStarsAnimation linear infinite;
+  animation-duration: var(--star-duration);
+  will-change: transform;
+}
+
+@keyframes risingStarsAnimation {
+  0% {
+    transform: translateY(0);
+  }
+
+  100% {
+    transform: translateY(-2000px);
+  }
+}
+</style>
diff --git a/docs/app/components/theme-studio/ThemeStudioViewSwitcher.vue b/docs/app/components/theme-studio/ThemeStudioViewSwitcher.vue
new file mode 100644
index 0000000000..f19d4d40f9
--- /dev/null
+++ b/docs/app/components/theme-studio/ThemeStudioViewSwitcher.vue
@@ -0,0 +1,107 @@
+<script setup lang="ts">
+import type { PopoverProps } from '@nuxt/ui'
+
+defineOptions({ inheritAttrs: false })
+
+const props = withDefaults(defineProps<{
+  content?: PopoverProps['content']
+  /** Set where the trigger carries no visible label of its own. */
+  tooltip?: string
+}>(), {
+  content: () => ({ align: 'center' })
+})
+
+const open = defineModel<boolean>('open', { default: false })
+
+const { view, views } = useThemeStudioView()
+const viewIcons = useStudioViewIcons()
+const appConfig = useAppConfig()
+
+const activeView = computed(() => views.find(tab => tab.value === view.value))
+
+// The studio-only views (no /templates screenshot) lead; the template
+// pages follow under their own heading.
+const sections = [
+  { label: 'Studio views', items: views.filter(tab => !tab.image) },
+  { label: 'Template pages', items: views.filter(tab => tab.image) }
+]
+
+/**
+ * A 2-column card grid: each view is its /templates screenshot over label and
+ * blurb; the studio-only views (grid, a11y) get an icon tile. Scrolling
+ * belongs to the wrapper, so both sections move together.
+ */
+const gridUi = {
+  root: 'ring-0 rounded-none overflow-visible',
+  content: 'max-h-none overflow-visible',
+  group: 'p-0 grid grid-cols-2 gap-1',
+  item: 'flex-col p-2 rounded-lg ring-inset before:rounded-lg gap-2 data-[state=checked]:before:bg-elevated/50',
+  itemDescription: 'whitespace-normal line-clamp-2 text-xs p-0',
+  itemTrailing: 'hidden'
+}
+</script>
+
+<template>
+  <UPopover v-model:open="open" :content="props.content">
+    <UTooltip :text="props.tooltip" :disabled="!props.tooltip">
+      <UButton
+        :icon="viewIcons[view]"
+        :label="activeView?.label"
+        :trailing-icon="appConfig.ui.icons.chevronDown"
+        color="neutral"
+        variant="outline"
+        aria-label="Preview page"
+        v-bind="$attrs"
+      />
+    </UTooltip>
+
+    <template #content>
+      <div class="w-96 max-h-[70vh] overflow-y-auto p-1.5 overflow-x-hidden">
+        <template v-for="(section, index) in sections" :key="section.label">
+          <!-- the templates heading sits between the two grids -->
+          <template v-if="index">
+            <USeparator class="mt-2 -mx-1.5 w-[calc(100%+1rem)]" />
+
+            <div class="flex items-center justify-between gap-2 p-2 pb-1">
+              <span class="text-sm font-semibold text-highlighted">{{ section.label }}</span>
+
+              <UButton
+                to="/templates"
+                color="neutral"
+                variant="ghost"
+                size="sm"
+                label="View all templates"
+                trailing-icon="i-lucide-arrow-right"
+              />
+            </div>
+          </template>
+
+          <UListbox
+            v-model="view"
+            :items="section.items"
+            value-key="value"
+            :ui="gridUi"
+            :aria-label="section.label"
+            @update:model-value="open = false"
+          >
+            <template #item-leading="{ item }">
+              <UColorModeImage
+                v-if="item.image"
+                :light="`${item.image}-light.png`"
+                :dark="`${item.image}-dark.png`"
+                :alt="`${item.label} preview`"
+                width="654"
+                height="368"
+                loading="lazy"
+                class="w-full aspect-video rounded ring ring-default"
+              />
+              <span v-else class="w-full aspect-video rounded ring ring-default bg-elevated/50 flex items-center justify-center">
+                <UIcon :name="viewIcons[item.value]" class="size-6" />
+              </span>
+            </template>
+          </UListbox>
+        </template>
+      </div>
+    </template>
+  </UPopover>
+</template>
diff --git a/docs/app/composables/useGoogleFonts.ts b/docs/app/composables/useGoogleFonts.ts
new file mode 100644
index 0000000000..2687c6ad1c
--- /dev/null
+++ b/docs/app/composables/useGoogleFonts.ts
@@ -0,0 +1,45 @@
+export interface GoogleFont {
+  name: string
+  category: string
+}
+
+/**
+ * The full Google Fonts catalog (family + category, popularity-ordered),
+ * served by /api/fonts.json, the metadata endpoint itself has no CORS
+ * headers. Fetched lazily the first time a font picker opens and shared
+ * through useState so every picker searches the same copy.
+ */
+export function useGoogleFonts() {
+  const catalog = useState<GoogleFont[]>('google-fonts-catalog', () => [])
+  const status = useState<'idle' | 'loading' | 'ready' | 'error'>('google-fonts-status', () => 'idle')
+
+  async function load() {
+    if (status.value === 'ready' || status.value === 'loading') return
+    status.value = 'loading'
+    try {
+      catalog.value = await $fetch<GoogleFont[]>('/api/fonts.json')
+      status.value = 'ready'
+    } catch {
+      status.value = 'error'
+    }
+  }
+
+  /** Popularity-ordered matches, prefix matches ahead of substring hits. */
+  function search(query: string, limit = 30): GoogleFont[] {
+    const q = query.trim().toLowerCase()
+    if (!q) return []
+    const starts: GoogleFont[] = []
+    const contains: GoogleFont[] = []
+    for (const font of catalog.value) {
+      const name = font.name.toLowerCase()
+      if (name.startsWith(q)) {
+        if (starts.push(font) >= limit) break
+      } else if (contains.length < limit && name.includes(q)) {
+        contains.push(font)
+      }
+    }
+    return [...starts, ...contains].slice(0, limit)
+  }
+
+  return { catalog, status, load, search }
+}
diff --git a/docs/app/composables/useSearch.ts b/docs/app/composables/useSearch.ts
index 7d6c90fd67..9459f8ef46 100644
--- a/docs/app/composables/useSearch.ts
+++ b/docs/app/composables/useSearch.ts
@@ -3,6 +3,11 @@ export function useSearch() {
   const { frameworks } = useFrameworks()
   const { track } = useAnalytics()
   const { open, messages } = useChat()
+  // The ⌘K link glyphs follow the applied pack where an equivalent exists;
+  // the docs-nav-specific ones (square-play/-code/-function, panels, etc.)
+  // have no pack glyph and stay Lucide.
+  const studioIcons = useStudioIcons()
+  const extra = useStudioExtraIcons()
 
   const searchTerm = ref('')
 
@@ -22,7 +27,7 @@ export function useSearch() {
 
   const links = computed(() => [{
     label: 'Ask AI',
-    icon: 'i-lucide-bot-message-square',
+    icon: studioIcons.assistant,
     kbds: ['meta', 'i'],
     ui: {
       itemLeadingIcon: 'group-data-highlighted:not-group-data-disabled:text-primary'
@@ -65,7 +70,7 @@ export function useSearch() {
   }, {
     label: 'Community',
     description: 'Explore community projects and resources.',
-    icon: 'i-lucide-globe',
+    icon: extra.globe,
     to: '/community'
   }, {
     label: 'Playground',
@@ -87,7 +92,7 @@ export function useSearch() {
   }, {
     label: 'Team',
     description: 'Meet the team behind the project.',
-    icon: 'i-lucide-users',
+    icon: extra.users,
     to: '/team'
   }, {
     label: 'Releases',
@@ -97,7 +102,7 @@ export function useSearch() {
   }, {
     label: 'GitHub',
     description: 'Check out the repository on GitHub.',
-    icon: 'i-simple-icons-github',
+    icon: extra.github,
     to: 'https://github.com/nuxt/ui/releases',
     target: '_blank'
   }])
@@ -119,7 +124,7 @@ export function useSearch() {
     },
     items: [{
       label: 'Ask AI',
-      icon: 'i-lucide-bot-message-square',
+      icon: studioIcons.assistant,
       ui: {
         itemLeadingIcon: 'group-data-highlighted:not-group-data-disabled:text-primary'
       },
diff --git a/docs/app/composables/useStudioIcons.ts b/docs/app/composables/useStudioIcons.ts
new file mode 100644
index 0000000000..f7d88ad6a7
--- /dev/null
+++ b/docs/app/composables/useStudioIcons.ts
@@ -0,0 +1,31 @@
+import { toReactive } from '@vueuse/core'
+import { studioIcons, STUDIO_EXTRA_DEFAULTS, studioExtraOverrides } from '../utils/theme/icons'
+
+/**
+ * The studio-chrome glyphs (toolbar controls, Ask-AI, theme picker) for the
+ * ACTIVE icon pack, so the studio's own UI skins to the applied theme. Falls
+ * back to Lucide for any unrecognized pack name. Returned as a reactive object
+ * (not a ref), like useStudioExtraIcons, so `studioIcons.undo` resolves
+ * directly in both script and templates.
+ */
+export function useStudioIcons() {
+  // `icon` already reports the stock pack until mounted (see useTheme), so the
+  // chrome inherits that hydration-safety for free.
+  const { icon } = useTheme()
+  return toReactive(computed(() => studioIcons[icon.value as keyof typeof studioIcons] ?? studioIcons.lucide))
+}
+
+/**
+ * The extended functional glyphs the preview demos use (dashboard nav, account
+ * menus, etc.) resolved for the active pack, each pack's override merged over
+ * the Lucide defaults, so an unset pack/key falls back to Lucide. Returned as a
+ * reactive object (not a ref) so `extra.home` resolves directly in both script
+ * arrays and templates, exactly like `appConfig.ui.icons.*`.
+ */
+export function useStudioExtraIcons() {
+  const { icon } = useTheme()
+  return toReactive(computed(() => ({
+    ...STUDIO_EXTRA_DEFAULTS,
+    ...(studioExtraOverrides[icon.value as keyof typeof studioExtraOverrides] ?? {})
+  })))
+}
diff --git a/docs/app/composables/useTheme.ts b/docs/app/composables/useTheme.ts
index 9d643c8c54..02d72e5bbb 100644
--- a/docs/app/composables/useTheme.ts
+++ b/docs/app/composables/useTheme.ts
@@ -1,35 +1,34 @@
 import { defu } from 'defu'
-import { useLocalStorage } from '@vueuse/core'
-import { themeIcons, cssVariableDefaults } from '../utils/theme'
+import { THEME_TAG_IDS, THEME_STATE_KEYS } from '../utils/theme/storage'
+import type { FontPrefs } from '../utils/theme/storage'
+import { FONT_WEIGHT_DEFAULTS } from '../utils/theme/studio'
+import { themeIcons } from '../utils/theme/icons'
+import { cssVariableDefaults } from '../utils/theme/tokens'
+import { generateCSS, generateConfig, mergeUi, isDefaultStyle, styleTokens, DEFAULT_COLORS, THEME_DEFAULTS, SEMANTIC_ALIASES, LIBRARY_TOKEN_DEFAULTS } from '../utils/theme/engine'
+import type { ThemeDoc, ThemePalette } from '../utils/theme/engine'
 import { omit } from '#ui/utils'
 import colors from 'tailwindcss/colors'
 
-function readLocalStorage<T>(key: string, fallback: T): T {
-  if (!import.meta.client) return fallback
-  try {
-    const raw = window.localStorage.getItem(key)
-    return raw ? JSON.parse(raw) : fallback
-  } catch {
-    return fallback
-  }
-}
-
-// AI `applyTheme` output is untrusted and ends up concatenated into <style> rules, so
-// only persist values that are plain CSS-safe tokens. This is the single write boundary,
-// which keeps every downstream sink (live useHead styles and the FOUC inline scripts) safe.
+// AI `applyTheme` output is untrusted and gets concatenated into <style> rules,
+// this is the single write boundary, so only CSS-safe tokens may persist.
 const SAFE_NAME = /^[\w -]{1,50}$/
+
+/** The three groups every font select offers. */
+export type FontCategory = 'Sans' | 'Serif' | 'Mono'
 const SAFE_HEX = /^#[0-9a-f]{3,8}$/i
+// the engine's canonical shade format: `oklch(62.3% 0.214 259.815)`
+const SAFE_OKLCH = /^oklch\(\d{1,3}(?:\.\d+)?% \d(?:\.\d+)? \d{1,3}(?:\.\d+)?\)$/i
 const SAFE_CSS_VAR_KEY = /^--[\w-]+$/
-const SAFE_CSS_VAR_VALUE = /^(?:var\(--[\w-]+\)|#[0-9a-f]{3,8}|[a-z]+)$/i
+const SAFE_CSS_VAR_VALUE = /^(?:var\(--[\w-]+\)|#[0-9a-f]{3,8}|[a-z]+|-?\d{1,3}(?:\.\d+)?(?:px|%))$/i
 
 function sanitizeCustomColors(input: Record<string, any>): Record<string, Record<string, string>> {
   const result: Record<string, Record<string, string>> = {}
   for (const [name, shades] of Object.entries(input)) {
     if (!SAFE_NAME.test(name) || typeof shades !== 'object' || !shades) continue
     const safeShades: Record<string, string> = {}
-    for (const [shade, hex] of Object.entries(shades as Record<string, unknown>)) {
-      if (/^\d{2,3}$/.test(shade) && typeof hex === 'string' && SAFE_HEX.test(hex)) {
-        safeShades[shade] = hex
+    for (const [shade, value] of Object.entries(shades as Record<string, unknown>)) {
+      if (/^\d{2,3}$/.test(shade) && typeof value === 'string' && (SAFE_OKLCH.test(value) || SAFE_HEX.test(value))) {
+        safeShades[shade] = value
       }
     }
     if (Object.keys(safeShades).length) result[name] = safeShades
@@ -50,22 +49,83 @@ function sanitizeCSSVariables(input: { light?: Record<string, any>, dark?: Recor
   return { light: clean(input.light), dark: clean(input.dark) }
 }
 
+export type { FontPrefs }
+
 export function useTheme() {
   const appConfig = useAppConfig()
   const colorMode = useColorMode()
   const { track } = useAnalytics()
-  const { framework } = useFrameworks()
 
-  const color = computed(() => colorMode.value === 'dark' ? (colors as any)[appConfig.ui.colors.neutral][900] : 'white')
+  // sliders stream through setters at drag frequency, one event per burst
+  let trackedAt: number | undefined
+  function trackThrottled(...args: Parameters<typeof track>) {
+    if (!trackedAt || Date.now() - trackedAt > 2000) {
+      trackedAt = Date.now()
+      track(...args)
+    }
+  }
+  const { framework } = useFrameworks()
 
-  const aiThemeExtras = useState<Record<string, any>>('nuxt-ui-ai-theme', () => readLocalStorage('nuxt-ui-ai-theme', {}))
-  const customColorsData = useState<Record<string, Record<string, string>>>('nuxt-ui-custom-colors', () => readLocalStorage('nuxt-ui-custom-colors', {}))
-  const cssVariablesData = useState<{ light?: Record<string, string>, dark?: Record<string, string> }>('nuxt-ui-css-variables', () => readLocalStorage('nuxt-ui-css-variables', {}))
-  const _radius = useLocalStorage('nuxt-ui-radius', 0.25)
-  const _font = useLocalStorage('nuxt-ui-font', 'Public Sans')
-  const _iconSet = useLocalStorage('nuxt-ui-icons', 'lucide')
-  const _blackAsPrimary = useLocalStorage('nuxt-ui-black-as-primary', false)
+  // Defaults only. The saved theme is ASSIGNED by plugins/theme.ts on the
+  // client, never seeded here: the server renders this composable, so these
+  // keys are already in the SSR payload and an initializer would not re-run.
+  // That plugin also owns the single write (see utils/theme/storage.ts), so
+  // nothing in here touches localStorage.
+  const aiThemeExtras = useState<Record<string, any>>('nuxt-ui-ai-theme', () => ({}))
+  // Style-treatment bundles live in their OWN channel so restyling can never
+  // destroy preset/AI overrides sharing the same component keys. Derived from
+  // `stylePrefs`, so it is rebuilt on load rather than persisted.
+  const styleUiData = useState<Record<string, any>>('nuxt-ui-style-ui', () => ({}))
+  const customColorsData = useState<Record<string, Record<string, string>>>('nuxt-ui-custom-colors', () => ({}))
+
+  // The neutral may be a custom palette with no tailwindcss/colors entry,
+  // a throw here would abort the whole unhead flush.
+  const color = computed(() => {
+    const neutral = appConfig.ui.colors.neutral
+    // match the page background (docs light baseline is neutral-50, not white)
+    const shade = colorMode.value === 'dark' ? 900 : 50
+    return (colors as any)[neutral]?.[shade] || customColorsData.value[neutral]?.[shade] || (colors as any).slate[shade]
+  })
+  const cssVariablesData = useState<{ light?: Record<string, string>, dark?: Record<string, string> }>('nuxt-ui-css-variables', () => ({}))
+  /** The studio's style axis (it owns writes); read here for currentDoc/export. */
+  const stylePrefs = useState<ThemeDoc['style']>(THEME_STATE_KEYS.stylePrefs, () => ({}))
+  // useState, not useLocalStorage: these are app-level, so every useTheme call
+  // shares one ref directly instead of converging through storage events.
+  const _radius = useState('nuxt-ui-radius', () => THEME_DEFAULTS.radius as number)
+  const _fontSize = useState('nuxt-ui-font-size', () => THEME_DEFAULTS.fontSize as number)
+  const _iconSet = useState('nuxt-ui-icons', () => THEME_DEFAULTS.icons as string)
+  const _blackAsPrimary = useState('nuxt-ui-black-as-primary', () => false)
+
+  /**
+   * The whole font document in one JSON channel, shared with the FOUC script.
+   * Sparse, exactly like `ThemeDoc['font']` it is typed as: an absent field
+   * means "inherit", so a stock theme stores nothing.
+   */
+  const fontPrefs = useState<FontPrefs>('nuxt-ui-font', () => ({}))
+
+  function setFontPrefs(next: FontPrefs, options: { track?: boolean } = {}) {
+    // Normalize: defaults are absences, so hasCSSChanges/export stay clean.
+    const clean: FontPrefs = {}
+    if (next.sans && next.sans !== THEME_DEFAULTS.font) clean.sans = next.sans
+    if (next.serif) clean.serif = next.serif
+    if (next.mono) clean.mono = next.mono
+    const weights: NonNullable<FontPrefs['weights']> = {}
+    for (const step of ['normal', 'medium', 'semibold', 'bold'] as const) {
+      const weight = next.weights?.[step]
+      if (weight !== undefined && weight !== FONT_WEIGHT_DEFAULTS[step]) weights[step] = weight
+    }
+    if (Object.keys(weights).length) clean.weights = weights
+    if (next.uppercase) clean.uppercase = true
+    if (next.italic) clean.italic = true
+    if (next.letterSpacing !== undefined && next.letterSpacing !== 0) clean.letterSpacing = next.letterSpacing
+    if (next.lineHeight !== undefined && next.lineHeight !== 1.5) clean.lineHeight = next.lineHeight
+
+    fontPrefs.value = clean
+    if (options.track !== false) trackThrottled('Theme Changed', { setting: 'fontPrefs' })
+  }
 
+  // taupe/mauve/mist/olive ship in tailwind's theme.css but not (yet) the
+  // tailwindcss/colors JS export, swatches resolve them from CSS variables
   const neutralColors = ['slate', 'gray', 'zinc', 'neutral', 'stone', 'taupe', 'mauve', 'mist', 'olive']
   const neutral = computed({
     get() {
@@ -73,7 +133,6 @@ export function useTheme() {
     },
     set(option) {
       appConfig.ui.colors.neutral = option
-      window.localStorage.setItem('nuxt-ui-neutral', appConfig.ui.colors.neutral)
       track('Theme Changed', { setting: 'neutral', value: option })
     }
   })
@@ -86,31 +145,67 @@ export function useTheme() {
     },
     set(option) {
       appConfig.ui.colors.primary = option
-      window.localStorage.setItem('nuxt-ui-primary', appConfig.ui.colors.primary)
       setBlackAsPrimary(false)
       track('Theme Changed', { setting: 'primary', value: option })
     }
   })
 
-  const radiuses = [0, 0.125, 0.25, 0.375, 0.5]
+  const radiuses = [0, 0.125, 0.25, 0.375, 0.5, 0.625, 0.75]
   const radius = computed({
     get() {
       return _radius.value
     },
     set(option) {
       _radius.value = option
-      track('Theme Changed', { setting: 'radius', value: option })
+      trackThrottled('Theme Changed', { setting: 'radius', value: option })
     }
   })
 
-  const fonts = ['Public Sans', 'DM Sans', 'Geist', 'Inter', 'Poppins', 'Outfit', 'Raleway']
+  const fontSize = computed({
+    get() {
+      return _fontSize.value
+    },
+    set(option) {
+      _fontSize.value = option
+      trackThrottled('Theme Changed', { setting: 'fontSize', value: option })
+    }
+  })
+
+  /**
+   * The shortlist every font select opens on, grouped by what the face is
+   * rather than by which slot it is for: the three stacks are independent, so
+   * nothing should stop a mono heading. Any other family is still reachable
+   * through the catalog search.
+   */
+  const fonts: Array<{ name: string, category: FontCategory }> = [
+    { name: 'Public Sans', category: 'Sans' },
+    { name: 'Inter', category: 'Sans' },
+    { name: 'DM Sans', category: 'Sans' },
+    { name: 'Geist', category: 'Sans' },
+    { name: 'Outfit', category: 'Sans' },
+    { name: 'Poppins', category: 'Sans' },
+    { name: 'Raleway', category: 'Sans' },
+    { name: 'Roboto', category: 'Sans' },
+    { name: 'Comic Neue', category: 'Sans' },
+    { name: 'Source Serif 4', category: 'Serif' },
+    { name: 'Lora', category: 'Serif' },
+    { name: 'Playfair Display', category: 'Serif' },
+    { name: 'Merriweather', category: 'Serif' },
+    { name: 'Instrument Serif', category: 'Serif' },
+    { name: 'Geist Mono', category: 'Mono' },
+    { name: 'JetBrains Mono', category: 'Mono' },
+    { name: 'Fira Code', category: 'Mono' },
+    { name: 'IBM Plex Mono', category: 'Mono' },
+    { name: 'Space Mono', category: 'Mono' }
+  ]
 
+  /** The body family, the `sans` field of the font document. */
   const font = computed({
     get() {
-      return _font.value
+      return fontPrefs.value.sans ?? THEME_DEFAULTS.font
     },
     set(option) {
-      _font.value = option
+      setFontPrefs({ ...fontPrefs.value, sans: option }, { track: false })
       track('Theme Changed', { setting: 'font', value: option })
     }
   })
@@ -119,18 +214,51 @@ export function useTheme() {
     label: 'Lucide',
     icon: 'i-lucide-feather',
     value: 'lucide'
+  }, {
+    label: 'Bootstrap',
+    icon: 'i-bi-bootstrap',
+    value: 'bootstrap'
+  }, {
+    label: 'Heroicons',
+    icon: 'i-simple-icons-tailwindcss',
+    value: 'heroicons'
+  }, {
+    label: 'Iconoir',
+    icon: 'i-iconoir-iconoir',
+    value: 'iconoir'
+  }, {
+    label: 'Material Symbols',
+    icon: 'i-simple-icons-materialdesign',
+    value: 'material'
   }, {
     label: 'Phosphor',
     icon: 'i-ph-phosphor-logo',
     value: 'phosphor'
+  }, {
+    label: 'Pixelart',
+    icon: 'i-pixelarticons-pixelarticons',
+    value: 'pixelarticons'
+  }, {
+    label: 'Remix',
+    icon: 'i-ri-remixicon-line',
+    value: 'remix'
   }, {
     label: 'Tabler',
     icon: 'i-tabler-brand-tabler',
     value: 'tabler'
   }]
+  // The saved pack is client-only, so anything rendered FROM it, the studio
+  // chrome, a picker's own brand glyph, would differ from the server on the
+  // first client render, and Vue only warns about a mismatched class, it never
+  // patches it. Reporting the stock pack until mounted keeps that first render
+  // honest; the flip afterwards is an ordinary update, which does repaint.
+  // Writes are unaffected, and `_iconSet` stays ungated for dirty checks.
+  const iconMounted = ref(false)
+  onMounted(() => (iconMounted.value = true))
+
   const icon = computed({
     get() {
-      return _iconSet.value
+      return iconMounted.value ? _iconSet.value : 'lucide'
     },
     set(option) {
       _iconSet.value = option
@@ -167,13 +295,46 @@ export function useTheme() {
   const hasCSSVariables = computed(() => Object.keys(cssVariablesData.value.light || {}).length > 0 || Object.keys(cssVariablesData.value.dark || {}).length > 0)
 
   const radiusStyle = computed(() => `:root { --ui-radius: ${_radius.value}rem; }`)
+  // font-size scales every rem-based metric on the page
+  const fontSizeStyle = computed(() => _fontSize.value !== 16 ? `html { font-size: ${_fontSize.value}px; }` : 'html {}')
   const blackAsPrimaryStyle = computed(() => _blackAsPrimary.value ? `:root { --ui-primary: black; } .dark { --ui-primary: white; }` : ':root {}')
-  const fontStyle = computed(() => `:root { --font-sans: '${_font.value}', sans-serif; }`)
+  const fontStyle = computed(() => {
+    // fonts hydrate unvalidated from localStorage, re-assert SAFE_NAME at
+    // the sink so a tampered name can't break out of the quoted string
+    const prefs = fontPrefs.value
+    const safeFont = prefs.sans && SAFE_NAME.test(prefs.sans) ? prefs.sans : 'Public Sans'
+    const parts = [`:root { --font-sans: '${safeFont}', sans-serif; }`]
+    // The stacks themselves, so `font-serif` / `font-mono` follow the theme.
+    if (prefs.serif && SAFE_NAME.test(prefs.serif)) parts.push(`:root { --font-serif: '${prefs.serif}', serif; }`)
+    if (prefs.mono && SAFE_NAME.test(prefs.mono)) parts.push(`:root { --font-mono: '${prefs.mono}', monospace; }`)
+    const weights = prefs.weights || {}
+    const weightVars = (Object.keys(weights) as Array<keyof typeof weights>)
+      .map(step => `--font-weight-${step}: ${weights[step]};`)
+    if (weightVars.length) {
+      parts.push(`:root { ${weightVars.join(' ')} }`)
+    }
+    const bodyRules: string[] = []
+    if (weights.normal !== undefined) bodyRules.push(`font-weight: ${weights.normal};`)
+    if (prefs.uppercase) bodyRules.push('text-transform: uppercase;')
+    if (prefs.italic) bodyRules.push('font-style: italic;')
+    if (prefs.letterSpacing !== undefined) bodyRules.push(`letter-spacing: ${prefs.letterSpacing}em;`)
+    if (prefs.lineHeight !== undefined) bodyRules.push(`line-height: ${prefs.lineHeight};`)
+    if (bodyRules.length) {
+      parts.push(`body { ${bodyRules.join(' ')} }`)
+    }
+    // No element rules here: preflight points `code`/`kbd`/`pre`/`samp` at
+    // --font-mono, and the h1–h6 rule that reads --font-serif lives in
+    // main.css, inside `@layer base` so `font-mono` on a heading still wins.
+    // Injected here it would be unlayered, and outrank every utility.
+    return parts.join(' ')
+  })
   const customColorsStyle = computed(() => {
     const entries = Object.entries(customColorsData.value)
-    if (!entries.length) return ''
+    // non-empty sentinel: unhead won't patch an emptied innerHTML, leaving
+    // the FOUC-written tag stale after a reactive-only reset (immediate: false)
+    if (!entries.length) return ':root {}'
     const vars = entries.flatMap(([name, shades]) =>
-      Object.entries(shades).map(([shade, hex]) => `--color-${name}-${shade}: ${hex};`)
+      Object.entries(shades).map(([shade, color]) => `--color-${name}-${shade}: ${color};`)
     )
     return `:root { ${vars.join(' ')} }`
   })
@@ -188,31 +349,40 @@ export function useTheme() {
       const full = { ...cssVariableDefaults.dark, ...data.dark }
       parts.push(`.dark { ${Object.entries(full).map(([k, v]) => `${k}: ${v};`).join(' ')} }`)
     }
-    return parts.join(' ')
+    // same sentinel rationale as customColorsStyle
+    return parts.length ? parts.join(' ') : ':root {}'
   })
 
-  const link = computed(() => {
-    const name = _font.value
-    if (name === 'Public Sans') return []
-    return [{
+  /** Google Fonts stylesheet link for a family (Public Sans is bundled). */
+  function fontLink(name: string) {
+    return {
       rel: 'stylesheet' as const,
-      href: `https://fonts.googleapis.com/css2?family=${encodeURIComponent(name)}:wght@400;500;600;700&display=swap`,
+      href: `https://fonts.googleapis.com/css2?family=${encodeURIComponent(name)}:wght@300;400;500;600;700;800&display=swap`,
       id: `font-${name.toLowerCase().replace(/\s+/g, '-')}`
-    }]
+    }
+  }
+
+  const link = computed(() => {
+    // Same guard as fontStyle's, so a name the stylesheet refuses can't still
+    // cost a Google Fonts request.
+    const names = new Set([fontPrefs.value.sans, fontPrefs.value.serif, fontPrefs.value.mono].filter((name): name is string => !!name && name !== 'Public Sans' && SAFE_NAME.test(name)))
+    return [...names].map(fontLink)
   })
 
   const style = [
     { innerHTML: radiusStyle, id: 'nuxt-ui-radius', tagPriority: -2 },
+    { innerHTML: fontSizeStyle, id: 'nuxt-ui-font-size', tagPriority: -2 },
     { innerHTML: blackAsPrimaryStyle, id: 'nuxt-ui-black-as-primary', tagPriority: -2 },
     { innerHTML: fontStyle, id: 'nuxt-ui-font', tagPriority: -2 },
-    { innerHTML: customColorsStyle, id: 'chat-custom-colors', tagPriority: -2 },
-    { innerHTML: cssVariablesStyle, id: 'chat-css-variables', tagPriority: -2 }
+    { innerHTML: customColorsStyle, id: THEME_TAG_IDS.customColors, tagPriority: -2 },
+    { innerHTML: cssVariablesStyle, id: THEME_TAG_IDS.cssVariables, tagPriority: -2 }
   ]
 
   const hasCSSChanges = computed(() => {
     return _radius.value !== 0.25
+      || _fontSize.value !== 16
       || _blackAsPrimary.value
-      || _font.value !== 'Public Sans'
+      || Object.keys(fontPrefs.value).length > 0
       || hasCustomColors.value
       || hasCSSVariables.value
   })
@@ -225,117 +395,115 @@ export function useTheme() {
       || !!aiThemeExtras.value.ui
   })
 
-  function exportCSS(): string {
-    track('Theme Exported', { type: 'CSS' })
-
-    const lines = [
-      '@import "tailwindcss";',
-      '@import "@nuxt/ui";'
-    ]
+  /** Snapshot the live theme state as a sparse ThemeDoc, the export generators' input. */
+  function currentDoc(): ThemeDoc {
+    const doc: ThemeDoc = { version: 1 }
 
-    if (_font.value !== 'Public Sans') {
-      lines.push('', '@theme {', `  --font-sans: '${_font.value}', sans-serif;`, '}')
-    }
-
-    const colorLines: string[] = []
-    for (const [name, shades] of Object.entries(customColorsData.value)) {
-      for (const [shade, hex] of Object.entries(shades)) {
-        colorLines.push(`  --color-${name}-${shade}: ${hex};`)
+    const colorOverrides: Record<string, string> = {}
+    for (const [key, def] of Object.entries(DEFAULT_COLORS)) {
+      const value = (appConfig.ui.colors as any)[key]
+      if (value && value !== def) {
+        colorOverrides[key] = value
       }
     }
-
-    if (colorLines.length) {
-      lines.push('', '@theme static {', ...colorLines, '}')
-    }
-
-    const lightOverrides = Object.entries(cssVariablesData.value.light || {}).filter(([key, val]) => val !== cssVariableDefaults.light[key as keyof typeof cssVariableDefaults.light])
-    const darkOverrides = Object.entries(cssVariablesData.value.dark || {}).filter(([key, val]) => val !== cssVariableDefaults.dark[key as keyof typeof cssVariableDefaults.dark])
-
-    const rootLines: string[] = []
-    if (_radius.value !== 0.25) {
-      rootLines.push(`  --ui-radius: ${_radius.value}rem;`)
-    }
-    if (_blackAsPrimary.value) {
-      rootLines.push('  --ui-primary: black;')
-    }
-
-    if (rootLines.length) {
-      lines.push('', ':root {', ...rootLines, '}')
-    }
-
-    if (lightOverrides.length) {
-      lines.push('', ':root, .light {', ...lightOverrides.map(([key, val]) => `  ${key}: ${val};`), '}')
+    if (Object.keys(colorOverrides).length) {
+      doc.colors = colorOverrides
+    }
+
+    if (_blackAsPrimary.value) doc.blackAsPrimary = true
+    if (_radius.value !== THEME_DEFAULTS.radius) doc.radius = _radius.value
+    if (_fontSize.value !== THEME_DEFAULTS.fontSize) doc.fontSize = _fontSize.value
+    // setFontPrefs already normalized this to the doc's own sparse shape,
+    // so it only needs copying out of the reactive object.
+    const fontDoc: ThemeDoc['font'] = {
+      ...fontPrefs.value,
+      ...(fontPrefs.value.weights ? { weights: { ...fontPrefs.value.weights } } : {})
+    }
+    if (Object.keys(fontDoc).length) doc.font = fontDoc
+    if (_iconSet.value !== THEME_DEFAULTS.icons) doc.icons = _iconSet.value
+
+    // Only alias-referenced palettes export. Reference by CURRENT value, not
+    // overrides, a custom palette can shadow a default name and must still export.
+    const referenced = new Set(Object.values(appConfig.ui.colors as Record<string, string>))
+    const paletteEntries = Object.entries(customColorsData.value).filter(([name]) => referenced.has(name))
+    if (paletteEntries.length) {
+      doc.palettes = Object.fromEntries(paletteEntries.map(([name, shades]) => [name, { shades: shades as ThemePalette['shades'] }]))
+    }
+
+    // read from reactive state, not localStorage, so watchers re-run on style edits
+    const style = stylePrefs.value
+    if (!isDefaultStyle(style)) {
+      doc.style = style
+    }
+
+    // Diff against LIBRARY defaults (exports sit on a stock install), drop
+    // studio-only vars, and keep only values that diverge from the style
+    // expansion, doc.style already accounts for the rest.
+    const styleVars = doc.style ? styleTokens(doc.style) : { light: {}, dark: {} }
+    const light = Object.fromEntries(Object.entries(cssVariablesData.value.light || {}).filter(([key, val]) => !key.startsWith('--studio-') && val !== LIBRARY_TOKEN_DEFAULTS.light[key as keyof typeof LIBRARY_TOKEN_DEFAULTS.light] && val !== (styleVars.light as Record<string, string>)[key]))
+    const dark = Object.fromEntries(Object.entries(cssVariablesData.value.dark || {}).filter(([key, val]) => !key.startsWith('--studio-') && val !== LIBRARY_TOKEN_DEFAULTS.dark[key as keyof typeof LIBRARY_TOKEN_DEFAULTS.dark] && val !== (styleVars.dark as Record<string, string>)[key]))
+    if (Object.keys(light).length || Object.keys(dark).length) {
+      doc.tokens = {
+        ...(Object.keys(light).length ? { light } : {}),
+        ...(Object.keys(dark).length ? { dark } : {})
+      }
     }
 
-    const darkLines: string[] = []
-    if (_blackAsPrimary.value) {
-      darkLines.push('  --ui-primary: white;')
-    }
-    if (darkOverrides.length) {
-      darkLines.push(...darkOverrides.map(([key, val]) => `  ${key}: ${val};`))
+    const extras = aiThemeExtras.value
+    if (extras.ui && Object.keys(extras.ui).length) {
+      doc.components = extras.ui
     }
 
-    if (darkLines.length) {
-      lines.push('', '.dark {', ...darkLines, '}')
-    }
+    return doc
+  }
 
-    return lines.join('\n')
+  // pure generation, callers track 'Theme Exported' on the actual copy
+  function exportCSS(): string {
+    return generateCSS(currentDoc())
   }
 
   function exportConfig(): string {
-    track('Theme Exported', { type: 'Config', framework: framework.value })
+    return generateConfig(currentDoc(), framework.value)
+  }
 
-    const config: Record<string, any> = {}
+  function injectCustomColors(customColors: Record<string, Record<string, string>>) {
+    customColorsData.value = { ...customColorsData.value, ...customColors }
+  }
 
-    const defaultColors: Record<string, string> = { primary: 'green', neutral: 'slate', secondary: 'blue', success: 'green', info: 'blue', warning: 'yellow', error: 'red' }
-    const colorEntries = Object.entries(defaultColors).filter(([key, def]) => (appConfig.ui.colors as any)[key] !== def)
-    if (colorEntries.length) {
-      config.ui = { colors: Object.fromEntries(colorEntries.map(([key]) => [key, (appConfig.ui.colors as any)[key]])) }
+  function removeCSSVariables(keys: { light?: string[], dark?: string[] }) {
+    const next = {
+      light: Object.fromEntries(Object.entries(cssVariablesData.value.light || {}).filter(([key]) => !keys.light?.includes(key))),
+      dark: Object.fromEntries(Object.entries(cssVariablesData.value.dark || {}).filter(([key]) => !keys.dark?.includes(key)))
+    }
+    cssVariablesData.value = next
+    if (import.meta.client && !Object.keys(next.light).length && !Object.keys(next.dark).length) {
+      document.getElementById(THEME_TAG_IDS.cssVariables)?.replaceChildren()
     }
+  }
 
-    if (_iconSet.value !== 'lucide') {
-      const iconMapping = themeIcons[_iconSet.value as keyof typeof themeIcons]
-      config.ui = config.ui || {}
-      config.ui.icons = iconMapping
+  /**
+   * Rebuild `appConfig.ui.<component>` for the given keys: style bundle
+   * first, preset/AI extras last so explicit overrides win the class merge.
+   */
+  function recomposeComponentOverrides(keys: Iterable<string>) {
+    for (const key of keys) {
+      const merged = mergeUi(
+        { [key]: styleUiData.value[key] },
+        { [key]: aiThemeExtras.value.ui?.[key] }
+      )[key]
+      ;(appConfig.ui as any)[key] = merged && Object.keys(merged).length ? merged : undefined
     }
+  }
 
-    const extras = aiThemeExtras.value
-    if (extras.ui) {
-      config.ui = config.ui || {}
-      Object.assign(config.ui, extras.ui)
-    }
-
-    const configString = JSON.stringify(config, null, 2)
-      .replace(/"([^"]+)":/g, '$1:')
-      .replace(/"/g, '\'')
-
-    if (framework.value === 'vue') {
-      const pluginConfig = config.ui
-        ? JSON.stringify({ ui: config.ui }, null, 2)
-            .replace(/"([^"]+)":/g, '$1:')
-            .replace(/"/g, '\'')
-        : '{}'
-      return [
-        'import { defineConfig } from \'vite\'',
-        'import vue from \'@vitejs/plugin-vue\'',
-        'import ui from \'@nuxt/ui/vite\'',
-        '',
-        `export default defineConfig({`,
-        '  plugins: [',
-        '    vue(),',
-        `    ui(${pluginConfig.split('\n').map((line, i) => i === 0 ? line : '    ' + line).join('\n')})`,
-        '  ]',
-        '})'
-      ].join('\n')
-    }
-
-    return `export default defineAppConfig(${configString})`
+  /** Replace the style treatment's component bundle wholesale. */
+  function setStyleUi(ui: Record<string, any>) {
+    const touched = new Set([...Object.keys(styleUiData.value), ...Object.keys(ui)])
+    styleUiData.value = ui
+    recomposeComponentOverrides(touched)
   }
 
-  function injectCustomColors(customColors: Record<string, Record<string, string>>) {
-    const merged = { ...customColorsData.value, ...customColors }
-    customColorsData.value = merged
-    window.localStorage.setItem('nuxt-ui-custom-colors', JSON.stringify(merged))
+  function removeCustomColors(names: string[]) {
+    customColorsData.value = Object.fromEntries(Object.entries(customColorsData.value).filter(([name]) => !names.includes(name)))
   }
 
   function injectCSSVariables(cssVariables: { light?: Record<string, string>, dark?: Record<string, string> }) {
@@ -344,27 +512,61 @@ export function useTheme() {
       dark: { ...cssVariablesData.value.dark, ...cssVariables.dark }
     }
     cssVariablesData.value = merged
-    window.localStorage.setItem('nuxt-ui-css-variables', JSON.stringify(merged))
   }
 
-  function applyThemeSettings(settings: Record<string, any>) {
-    if (settings.customColors && typeof settings.customColors === 'object') {
-      const safeCustomColors = sanitizeCustomColors(settings.customColors)
-      if (Object.keys(safeCustomColors).length) injectCustomColors(safeCustomColors)
-    }
+  function applyThemeSettings(settings: Record<string, any>, options: { track?: boolean } = {}) {
+    // sanitize up front, later checks must consult the SANITIZED set
+    const safeCustomColors = settings.customColors && typeof settings.customColors === 'object'
+      ? sanitizeCustomColors(settings.customColors)
+      : {}
+    if (Object.keys(safeCustomColors).length) injectCustomColors(safeCustomColors)
 
     if (settings.cssVariables && typeof settings.cssVariables === 'object') {
       injectCSSVariables(sanitizeCSSVariables(settings.cssVariables))
     }
 
     if (settings.primary && SAFE_NAME.test(settings.primary)) primary.value = settings.primary
-    if (settings.neutral && neutralColors.includes(settings.neutral)) neutral.value = settings.neutral
+    // any known palette is a valid neutral, custom ones included
+    if (settings.neutral && SAFE_NAME.test(settings.neutral) && (neutralColors.includes(settings.neutral) || primaryColors.includes(settings.neutral) || (customColorsData.value[settings.neutral] || safeCustomColors[settings.neutral]))) neutral.value = settings.neutral
     if (settings.radius !== undefined && Number.isFinite(Number(settings.radius))) radius.value = Number(settings.radius)
-    if (settings.font && SAFE_NAME.test(settings.font)) font.value = settings.font
+    // clamped: these scale the whole page
+    if (settings.fontSize !== undefined && Number.isFinite(Number(settings.fontSize))) fontSize.value = Math.min(20, Math.max(12, Number(settings.fontSize)))
+    // All three stacks and the body treatment share one channel, so they are
+    // applied in one pass: setFontPrefs takes the WHOLE object, and any field
+    // the payload leaves out has to fall back to what is already set. A
+    // payload naming only the heading font would otherwise clear the rest,
+    // the body family included.
+    if (settings.fontSans !== undefined || settings.fontSerif !== undefined || settings.fontMono !== undefined
+      || settings.fontWeights !== undefined || settings.fontBody !== undefined) {
+      const current = fontPrefs.value
+      const rawWeights = settings.fontWeights && typeof settings.fontWeights === 'object' ? settings.fontWeights : current.weights || {}
+      const weights: NonNullable<FontPrefs['weights']> = {}
+      for (const step of ['normal', 'medium', 'semibold', 'bold'] as const) {
+        const weight = Number(rawWeights[step])
+        if (Number.isFinite(weight)) weights[step] = Math.min(900, Math.max(100, weight))
+      }
+      const body = settings.fontBody && typeof settings.fontBody === 'object' ? settings.fontBody : undefined
+      const em = (value: unknown) => Number.isFinite(Number(value)) ? Math.min(1, Math.max(-0.2, Number(value))) : undefined
+      const leading = (value: unknown) => Number.isFinite(Number(value)) ? Math.min(3, Math.max(0.8, Number(value))) : undefined
+      // Absent OR unusable keeps what is set: a rejected name must not read
+      // as "clear this slot".
+      const family = (value: unknown, fallback?: string) =>
+        typeof value === 'string' && SAFE_NAME.test(value) ? value : fallback
+      setFontPrefs({
+        sans: family(settings.fontSans, current.sans),
+        serif: family(settings.fontSerif, current.serif),
+        mono: family(settings.fontMono, current.mono),
+        weights,
+        uppercase: body ? !!body.uppercase : current.uppercase,
+        italic: body ? !!body.italic : current.italic,
+        letterSpacing: body ? em(body.letterSpacing) : current.letterSpacing,
+        lineHeight: body ? leading(body.lineHeight) : current.lineHeight
+      })
+    }
     if (settings.icons && settings.icons in themeIcons) icon.value = settings.icons
     if (settings.blackAsPrimary !== undefined) setBlackAsPrimary(!!settings.blackAsPrimary)
 
-    const colorKeys = ['secondary', 'success', 'info', 'warning', 'error'] as const
+    const colorKeys = SEMANTIC_ALIASES
     const savedExtras: Record<string, any> = { ...aiThemeExtras.value }
 
     for (const color of colorKeys) {
@@ -378,33 +580,44 @@ export function useTheme() {
     if (settings.ui) {
       savedExtras.ui = savedExtras.ui || {}
       for (const [key, value] of Object.entries(settings.ui)) {
-        // Skip `colors` (handled above) and prototype-chain keys that would pollute appConfig.ui when assigned.
-        if (key === 'colors' || key === '__proto__' || key === 'constructor' || key === 'prototype') continue
+        // skip colors (handled above), icons (a partial map would blank
+        // icons app-wide) and prototype-polluting keys
+        if (key === 'colors' || key === 'icons' || key === '__proto__' || key === 'constructor' || key === 'prototype') continue
 
-        const merged = defu(value as Record<string, any>, (appConfig.ui as any)[key] || {}, savedExtras.ui[key] || {})
-        ;(appConfig.ui as any)[key] = merged
-        savedExtras.ui[key] = merged
+        savedExtras.ui[key] = defu(value as Record<string, any>, savedExtras.ui[key] || {})
       }
     }
 
-    aiThemeExtras.value = savedExtras
-    window.localStorage.setItem('nuxt-ui-ai-theme', JSON.stringify(savedExtras))
+    // only rewrite the channel when touched, slider/curve drags stream
+    // through here and must not reactively wake the AI extras every tick
+    const touchedExtras = settings.ui || colorKeys.some(color => settings[color] && SAFE_NAME.test(settings[color]))
+    if (touchedExtras) {
+      aiThemeExtras.value = savedExtras
+    }
+    if (settings.ui) {
+      recomposeComponentOverrides(Object.keys(savedExtras.ui || {}))
+    }
 
-    track('AI Theme Applied')
+    // hot paths (slider/curve drags) opt out of the analytics event
+    if (options.track !== false) {
+      track('AI Theme Applied')
+    }
   }
 
-  function resetTheme() {
-    track('Theme Reset')
-
-    appConfig.ui.colors.primary = 'green'
-    window.localStorage.removeItem('nuxt-ui-primary')
+  // track opt-out: applyDoc resets before applying, every preset swap and
+  // undo/redo would otherwise count as a "Theme Reset"
+  function resetTheme(options: { track?: boolean, immediate?: boolean } = {}) {
+    if (options.track !== false) {
+      track('Theme Reset')
+    }
 
-    appConfig.ui.colors.neutral = 'slate'
-    window.localStorage.removeItem('nuxt-ui-neutral')
+    appConfig.ui.colors.primary = DEFAULT_COLORS.primary
+    appConfig.ui.colors.neutral = DEFAULT_COLORS.neutral
 
-    _radius.value = 0.25
-    _font.value = 'Public Sans'
-    _iconSet.value = 'lucide'
+    _radius.value = THEME_DEFAULTS.radius
+    _fontSize.value = THEME_DEFAULTS.fontSize
+    fontPrefs.value = {}
+    _iconSet.value = THEME_DEFAULTS.icons
     appConfig.ui.icons = themeIcons.lucide as any
     _blackAsPrimary.value = false
 
@@ -421,16 +634,25 @@ export function useTheme() {
         (appConfig.ui as any)[key] = undefined
       }
     }
-    window.localStorage.removeItem('nuxt-ui-ai-theme')
-    window.localStorage.removeItem('nuxt-ui-custom-colors')
-    window.localStorage.removeItem('nuxt-ui-css-variables')
     aiThemeExtras.value = {}
     customColorsData.value = {}
     cssVariablesData.value = {}
 
-    if (import.meta.client) {
-      document.getElementById('chat-css-variables')?.replaceChildren()
-      document.getElementById('chat-custom-colors')?.replaceChildren()
+    // studio-owned state resets too, orphaned style prefs would silently
+    // resurrect on the next style click or export
+    setStyleUi({})
+    useState<Record<string, any>>(THEME_STATE_KEYS.stylePrefs).value = {}
+    useState<string | undefined>(THEME_STATE_KEYS.themePreset).value = undefined
+    // in-memory curve params too, or the palette editor re-persists them
+    useState<Record<string, any>>(THEME_STATE_KEYS.paletteParams).value = {}
+
+    // Imperative clearing makes a bare reset land the same frame, but a
+    // reset-then-reapply (preset swap, undo/redo) would flash the default
+    // theme, so those callers pass immediate: false and let reactivity swap
+    // the tags atomically.
+    if (import.meta.client && options.immediate !== false) {
+      document.getElementById(THEME_TAG_IDS.cssVariables)?.replaceChildren()
+      document.getElementById(THEME_TAG_IDS.customColors)?.replaceChildren()
     }
   }
 
@@ -446,8 +668,11 @@ export function useTheme() {
     setBlackAsPrimary,
     radiuses,
     radius,
+    fontSize,
     fonts,
     font,
+    fontPrefs,
+    setFontPrefs,
     icon,
     icons,
     modes,
@@ -455,6 +680,12 @@ export function useTheme() {
     hasCSSChanges,
     hasConfigChanges,
     configLabel: computed(() => framework.value === 'vue' ? 'vite.config.ts' : 'app.config.ts'),
+    currentDoc,
+    cssVariablesData,
+    customColorsData,
+    removeCustomColors,
+    removeCSSVariables,
+    setStyleUi,
     exportCSS,
     exportConfig,
     applyThemeSettings,
diff --git a/docs/app/composables/useThemeStudio.ts b/docs/app/composables/useThemeStudio.ts
new file mode 100644
index 0000000000..73b0d3a0aa
--- /dev/null
+++ b/docs/app/composables/useThemeStudio.ts
@@ -0,0 +1,494 @@
+import colors from 'tailwindcss/colors'
+import { THEME_STATE_KEYS, readStoredTheme } from '../utils/theme/storage'
+import { presets, DEFAULT_PRESET_ID, docToSettings, isDefaultTheme, generatePalette, applyPaletteEffects, isDefaultEffects, parseCssColor, styleComponents, styleTokens, sectionFingerprint, mergeSection, canonicalTokenShades, storedStopStep, nearestShade, TOKEN_SHADE_TARGETS, SECTION_GROUPS, DEFAULT_COLORS, SHADES, SHADES_ALL, SHADE_SETS } from '../utils/theme/engine'
+import type { SectionKey, ThemeDoc, ThemePreset, PaletteCurveParams, PaletteEffects, StoredPaletteParams, PalettePin, StyleOptions, Shade, ShadeStep, ShadeStop, ColorAlias, TokenRamp } from '../utils/theme/engine'
+
+export function useThemeStudio() {
+  const theme = useTheme()
+  const appConfig = useAppConfig()
+  const { track } = useAnalytics()
+
+  /**
+   * The BASELINE preset: stays set through ordinary edits (per-section
+   * dirty/reset measures against it) and is only replaced by another
+   * preset, a shuffle, an import or a full reset. Persisted so the menu
+   * still names it after a reload.
+   */
+  const activePreset = useState<string | undefined>(THEME_STATE_KEYS.themePreset, () => {
+    // Presets get renamed, so a persisted id can stop naming anything. Drop it
+    // rather than holding a baseline no preset defines, which would leave the
+    // pickers with nothing selected and every section reading dirty forever.
+    // assigned by plugins/theme.ts on the client, defaults on the server
+    return undefined
+  })
+
+  function setActivePreset(id: string | undefined) {
+    activePreset.value = id
+  }
+
+  /**
+   * Curve params per alias, kept so the editor stays editable across reloads.
+   * The ramps they generate ride the customColors channel; both come out of
+   * the same storage write, so they can no longer restore out of step.
+   */
+  const paletteParams = useState<Partial<Record<string, StoredPaletteParams>>>(THEME_STATE_KEYS.paletteParams, () => ({}))
+
+  function setPaletteParams(value: Partial<Record<string, StoredPaletteParams>>) {
+    paletteParams.value = value
+  }
+
+  // A persisted id can name a preset that no longer exists (they get renamed).
+  // The theme it applied is still restored, so the page would keep a look no
+  // preset can name and every picker would read Custom. Reset to stock: the
+  // doc came from a build that no longer exists, so there is nothing to
+  // preserve it against. This discards edits made on top of a since-renamed
+  // preset, the trade for the pickers and the page agreeing.
+  const presetHealed = useState('nuxt-ui-preset-healed', () => false)
+  if (import.meta.client && !presetHealed.value) {
+    presetHealed.value = true
+    const id = readStoredTheme().preset
+    if (id && !presets.some(preset => preset.id === id)) {
+      onNuxtReady(() => theme.resetTheme({ track: false }))
+    }
+  }
+
+  /** Default-variant and token-shade prefs; the expansion lives in the style-ui channel. */
+  const style = useState<StyleOptions>(THEME_STATE_KEYS.stylePrefs, () => ({}))
+
+  // The class bundle is an expansion of `style`, not stored state, so it is
+  // rebuilt from the restored prefs on load. That also means a generator
+  // change (new fragment classes) reaches already-saved themes for free,
+  // which used to need a self-heal comparing the two.
+  const bundleBuilt = useState('nuxt-ui-style-bundle-built', () => false)
+  if (import.meta.client && !bundleBuilt.value) {
+    bundleBuilt.value = true
+    try {
+      const expected = styleComponents(style.value)
+      if (Object.keys(expected).length) onNuxtReady(() => theme.setStyleUi(expected))
+    } catch {
+      // a throwing expansion (corrupt persisted style) shouldn't be permanent
+      bundleBuilt.value = false
+    }
+  }
+
+  // Shared across composable instances so the analytics throttle holds no
+  // matter which component fires the event.
+  const trackedAt = useState<number | undefined>('nuxt-ui-style-tracked-at', () => undefined)
+
+  // Style and palette edits share one clock deliberately: a drag session
+  // is one gesture, not two metrics.
+  function trackThrottled(...args: Parameters<typeof track>) {
+    if (!trackedAt.value || Date.now() - trackedAt.value > 2000) {
+      trackedAt.value = Date.now()
+      track(...args)
+    }
+  }
+
+  function setStyle(options: StyleOptions) {
+    const previousStyle = style.value
+    const previous = styleTokens(previousStyle)
+    style.value = { ...style.value, ...options }
+
+    // Remove only the tokens the PREVIOUS style emitted and the next one
+    // doesn't, never preset/doc-owned values sharing the same names.
+    const tokens = styleTokens(style.value)
+    theme.removeCSSVariables({
+      light: Object.keys(previous.light).filter(key => !(key in tokens.light)),
+      dark: Object.keys(previous.dark).filter(key => !(key in tokens.dark))
+    })
+
+    // The class bundle lives in its own channel (never touches preset/AI
+    // overrides), and shade-only edits skip the component churn entirely.
+    const components = styleComponents(style.value)
+    if (JSON.stringify(components) !== JSON.stringify(styleComponents(previousStyle))) {
+      theme.setStyleUi(components)
+    }
+
+    if (Object.keys(tokens.light).length || Object.keys(tokens.dark).length) {
+      theme.applyThemeSettings({ cssVariables: tokens }, { track: false })
+    }
+
+    // Sliders stream through here at drag frequency, one event per burst.
+    trackThrottled('Theme Style Changed', {
+      variant: style.value.defaults?.variant || 'default',
+      size: style.value.defaults?.size || 'default'
+    })
+  }
+
+  function customPaletteName(alias: string) {
+    return `custom-${alias}`
+  }
+
+  function isCustomPalette(alias: string) {
+    return (appConfig.ui.colors as Record<string, string>)[alias] === customPaletteName(alias)
+  }
+
+  /**
+   * Every defined shade of a named palette as oklch, tailwind's JS values
+   * first, CSS variables as fallback. Sampled across every stop any density
+   * can emit, so a ramp generated at a finer density is read whole; a standard
+   * 11-stop ramp simply has no in-between vars and those drop out. The editor
+   * reads the density back from which stops came through.
+   */
+  function paletteShades(name: string): Partial<Record<Shade, string>> | undefined {
+    const tailwind = (colors as Record<string, any>)[name]
+    if (tailwind && typeof tailwind === 'object') {
+      // A stock tailwind ramp has only the 11 standard stops, the rest are
+      // undefined, and parseCssColor would throw on those. Skip absent shades
+      // so a full sweep degrades cleanly to the 11 present.
+      return Object.fromEntries(
+        SHADES_ALL
+          .filter(shade => tailwind[shade] != null)
+          .map(shade => [shade, parseCssColor(tailwind[shade])])
+          .filter(([, color]) => color)
+      )
+    }
+
+    if (import.meta.client) {
+      const styles = getComputedStyle(document.documentElement)
+      const cssName = name === 'neutral' ? 'old-neutral' : name
+      const entries = SHADES_ALL
+        .map(shade => [shade, parseCssColor(styles.getPropertyValue(`--color-${cssName}-${shade}`))] as const)
+        .filter(([, color]) => color)
+      if (entries.length >= 2) {
+        return Object.fromEntries(entries)
+      }
+    }
+    return undefined
+  }
+
+  /**
+   * Swatch-click entry point, for any color alias, always a real alias
+   * switch. A custom palette in place is dropped first (its curves and
+   * modifiers included), so the menu names the selection instead of a
+   * stale Custom; an open editor refits from the new color by itself.
+   */
+  function selectPalette(alias: ColorAlias, name: string) {
+    if (isCustomPalette(alias)) {
+      clearCustomPalette(alias)
+    }
+
+    if (alias === 'primary') {
+      theme.primary.value = name
+    } else if (alias === 'neutral') {
+      theme.neutral.value = name
+      // Stock neutrals need the white-literal remaps too, without them the
+      // preview (docs baseline: neutral-50 bg) diverges from the export
+      // (library baseline: white bg) for every tinted ramp.
+      theme.applyThemeSettings({ cssVariables: unownedNeutralRemaps() }, { track: false })
+    } else {
+      theme.applyThemeSettings({ [alias]: name }, { track: false })
+      track('Theme Changed', { setting: alias, value: name })
+    }
+  }
+
+  /**
+   * The library hardcodes five tokens to `white` (light `--ui-bg` and
+   * `--ui-text-inverted`; dark `--ui-text-highlighted`, `--ui-bg-inverted`
+   * and `--ui-border-inverted`), so a tinted neutral ramp would never reach
+   * them. Choosing a neutral re-routes all five through the ramp, which is
+   * also what makes the export reproduce the preview, since the docs
+   * baseline already shows neutral-50 as the page background.
+   */
+  const NEUTRAL_TOKEN_REMAPS = {
+    light: {
+      '--ui-bg': 'var(--ui-color-neutral-50)',
+      '--ui-text-inverted': 'var(--ui-color-neutral-50)'
+    },
+    dark: {
+      '--ui-text-highlighted': 'var(--ui-color-neutral-50)',
+      '--ui-bg-inverted': 'var(--ui-color-neutral-50)',
+      '--ui-border-inverted': 'var(--ui-color-neutral-50)'
+    }
+  }
+
+  /** Remaps minus any token the user's shade sliders already own. */
+  function unownedNeutralRemaps() {
+    const owned = style.value.tokenShades || {}
+    const filter = (mode: 'light' | 'dark', vars: Record<string, string>) =>
+      Object.fromEntries(Object.entries(vars).filter(([token]) => owned[token]?.[mode] === undefined))
+    return {
+      light: filter('light', NEUTRAL_TOKEN_REMAPS.light),
+      dark: filter('dark', NEUTRAL_TOKEN_REMAPS.dark)
+    }
+  }
+
+  /** The stops a ramp actually emits, its density when custom, else the standard 11. */
+  function rampStops(ramp?: string): readonly Shade[] {
+    return ramp && isCustomPalette(ramp) ? SHADE_SETS[storedStopStep(paletteParams.value[ramp])] : SHADES
+  }
+
+  /**
+   * A token shade pinned to an in-between stop only resolves while its ramp is
+   * a custom palette generating that stop, that's the only thing defining
+   * `--color-custom-<ramp>-<stop>`. When a ramp changes density, or is cleared
+   * / switched to a stock colour, that variable disappears, so snap any
+   * now-orphaned token to the nearest stop the ramp does emit rather than
+   * leaving a dangling reference (which renders transparent).
+   */
+  function sanitizeTokenShades() {
+    const shades = style.value.tokenShades
+    if (!shades) return
+    let changed = false
+    const next: NonNullable<StyleOptions['tokenShades']> = {}
+    for (const [token, modes] of Object.entries(shades)) {
+      const stops = rampStops(TOKEN_SHADE_TARGETS.find(target => target.token === token)?.ramp)
+      const fixed: { light?: ShadeStop, dark?: ShadeStop } = {}
+      for (const mode of ['light', 'dark'] as const) {
+        const value = modes[mode]
+        if (value === undefined) continue
+        if (typeof value === 'number' && !stops.includes(value)) {
+          fixed[mode] = nearestShade(value, stops)
+          changed = true
+        } else {
+          fixed[mode] = value
+        }
+      }
+      if (Object.keys(fixed).length) next[token] = fixed
+    }
+    if (changed) setStyle({ tokenShades: next })
+  }
+
+  /**
+   * Generate a ramp and point the alias at it. The base curves and the
+   * modifier lens persist separately, so a reload restores the editor's
+   * sliders instead of silently baking them into the curves.
+   */
+  function setPaletteFromCurve(alias: ColorAlias, base: PaletteCurveParams, effects?: PaletteEffects, amount = 100, step: ShadeStep = 100, pins: PalettePin[] = []) {
+    const name = customPaletteName(alias)
+    // The alias only needs pointing once. Live drags call this at ~16Hz; re-
+    // sending it every tick makes applyThemeSettings re-persist the AI-extras
+    // channel (a JSON.stringify + reactive wake) on every frame. Send it
+    // only when it actually changes.
+    const aliasAlreadySet = (appConfig.ui.colors as Record<string, string>)[alias] === name
+
+    theme.applyThemeSettings({
+      customColors: { [name]: generatePalette(applyPaletteEffects(base, effects, amount), step, pins) },
+      ...(aliasAlreadySet ? {} : { [alias]: name }),
+      // The remaps are var() references, not ramp colours, and are kept in
+      // sync with the shade sliders elsewhere, so they only need (re)sending
+      // when this call first points the alias at the ramp, not every tick.
+      ...(alias === 'neutral' && !aliasAlreadySet ? { cssVariables: unownedNeutralRemaps() } : {})
+    }, { track: false })
+    const entry: StoredPaletteParams = {
+      ...base,
+      ...(isDefaultEffects(effects, amount) ? {} : { effects, amount }),
+      ...(step !== 100 ? { stopStep: step } : {}),
+      ...(pins.length ? { pins } : {})
+    }
+    setPaletteParams({ ...paletteParams.value, [alias]: entry })
+
+    // A coarser density orphans any token pinned to a stop it no longer emits.
+    // Only writes when something actually moved, so the drag path is a no-op.
+    sanitizeTokenShades()
+
+    // Live drags call this at ~16Hz, one analytics event per burst is plenty.
+    trackThrottled('Theme Custom Palette', { alias })
+  }
+
+  /**
+   * Drop the custom ramp and its curve params. Callers (swatch selection)
+   * always set the alias right after, so no restore dance is needed, the
+   * default is just a safety net for a clear without a follow-up pick.
+   */
+  function clearCustomPalette(alias: ColorAlias) {
+    theme.removeCustomColors([customPaletteName(alias)])
+    if (alias === 'neutral') {
+      const remaps = unownedNeutralRemaps()
+      theme.removeCSSVariables({
+        light: Object.keys(remaps.light),
+        dark: Object.keys(remaps.dark)
+      })
+    }
+
+    theme.applyThemeSettings({ [alias]: DEFAULT_COLORS[alias] }, { track: false })
+
+    const { [alias]: _, ...rest } = paletteParams.value
+    setPaletteParams(rest)
+
+    // A stock ramp emits only the standard 11, snap any token off the rest.
+    sanitizeTokenShades()
+  }
+
+  /**
+   * Reflect a doc's token overrides back into the sidebar's shade settings
+   * where they are representable, so controls show the preset's reality
+   * instead of stale defaults. Only neutral-ramp refs map onto sliders;
+   * anything else (white/black literals, non-neutral refs) stays token-only.
+   */
+  /**
+   * The style axis a doc implies: its explicit style plus ramp-shaped token
+   * overrides promoted into tokenShades (canonicalTokenShades, shared with
+   * the section dirty/reset comparisons, which depend on this promotion
+   * being identical on both sides).
+   */
+  function deriveStyle(doc: ThemeDoc): StyleOptions {
+    const derived: StyleOptions = { ...(doc.style || {}) }
+    const shades = canonicalTokenShades(doc)
+    // guard: an empty tokenShades object would flip isDefaultStyle
+    if (Object.keys(shades).length) derived.tokenShades = shades
+    return derived
+  }
+
+  /** Replace the current theme with a document: reset, then apply overrides. */
+  function applyDoc(doc: ThemeDoc) {
+    // immediate: false, this reset is followed by the doc's own styles in the
+    // same call, so let the reactive tags swap atomically rather than clearing
+    // to the default theme for a frame (a white flash between presets).
+    theme.resetTheme({ track: false, immediate: false })
+    style.value = deriveStyle(doc)
+
+    if (!isDefaultTheme(doc)) {
+      theme.applyThemeSettings(docToSettings(doc), { track: false })
+      const components = styleComponents(style.value)
+      if (Object.keys(components).length) {
+        theme.setStyleUi(components)
+      }
+    }
+  }
+
+  function applyPreset(preset: ThemePreset) {
+    applyDoc(preset.doc)
+    setActivePreset(preset.id)
+
+    track('Theme Preset Applied', { preset: preset.id })
+  }
+
+  function pick<T>(items: readonly T[]): T {
+    return items[Math.floor(Math.random() * items.length)] as T
+  }
+
+  function shuffle() {
+    const doc: ThemeDoc = {
+      version: 1,
+      colors: {
+        primary: pick(theme.primaryColors),
+        neutral: pick(theme.neutralColors)
+      },
+      radius: pick(theme.radiuses),
+      icons: pick(theme.icons).value,
+      // body faces only, a shuffled monospace page is never the tasteful roll
+      font: { sans: pick(theme.fonts.filter(entry => entry.category === 'Sans')).name }
+    }
+
+    // An app-wide variant is the loud roll, sprinkled in rarely enough that
+    // most shuffles stay tasteful. Left off entirely otherwise, an empty
+    // `style` would ride into history and exports as a phantom key.
+    if (Math.random() < 0.25) {
+      doc.style = { defaults: { variant: pick(['solid', 'outline', 'soft', 'subtle'] as const) } }
+    }
+
+    if (Math.random() < 0.125) {
+      doc.blackAsPrimary = true
+      delete doc.colors!.primary
+    }
+
+    applyDoc(doc)
+    // applyDoc routes neutral through the plain setter, the shuffled
+    // neutral needs the same white-literal remaps selectPalette applies,
+    // or the preview diverges from the export for every tinted ramp.
+    theme.applyThemeSettings({ cssVariables: unownedNeutralRemaps() }, { track: false })
+    setActivePreset(undefined)
+
+    track('Theme Studio Shuffled')
+  }
+
+  /** Palette-name chips coloring shade-slider swatches, each alias's current ramp. */
+  const neutralChip = computed(() => theme.neutral.value === 'neutral' ? 'old-neutral' : theme.neutral.value)
+  const primaryChip = computed(() => isCustomPalette('primary') ? 'custom-primary' : theme.primary.value)
+
+  function rampChip(ramp: TokenRamp): string {
+    if (ramp === 'primary') return primaryChip.value
+    if (ramp === 'neutral') return neutralChip.value
+    const name = (appConfig.ui.colors as Record<string, string>)[ramp] || ramp
+    return name === 'neutral' ? 'old-neutral' : name
+  }
+
+  /* ----------------------------------------------- section reset/delta -- */
+
+  /**
+   * Dirty and reset are measured against the ACTIVE PRESET's doc (stock
+   * when none): "what did I touch since applying the preset". Reset splices
+   * the baseline's slice into the current doc and rides the same applyDoc
+   * path history restores use.
+   */
+  const baselineDoc = computed(() => presets.find(preset => preset.id === activePreset.value)?.doc ?? { version: 1 as const })
+
+  /** One key, or several when a fold owns more than one slice (Defaults). */
+  function sectionDirty(key: SectionKey | SectionKey[]) {
+    const keys = Array.isArray(key) ? key : [key]
+    return computed(() => keys.some(entry =>
+      sectionFingerprint(theme.currentDoc(), entry) !== sectionFingerprint(baselineDoc.value, entry)
+    ))
+  }
+
+  function groupDirty(group: keyof typeof SECTION_GROUPS) {
+    return computed(() => SECTION_GROUPS[group].some(key =>
+      sectionFingerprint(theme.currentDoc(), key) !== sectionFingerprint(baselineDoc.value, key)
+    ))
+  }
+
+  function resetSection(key: SectionKey | SectionKey[]) {
+    // several slices splice in one pass, one applyDoc, so a multi-key fold
+    // costs one history entry rather than one per slice
+    const keys = Array.isArray(key) ? key : [key]
+    // currentDoc embeds reactive slices, structuredClone chokes on Vue
+    // proxies, so round-trip to plain JSON first (history does the same)
+    const plain = JSON.parse(JSON.stringify(theme.currentDoc())) as ThemeDoc
+    // applyDoc resets everything first, which clears the persisted preset,
+    // but a section reset moves TOWARD the baseline; keep it
+    const preserved = activePreset.value
+    // applyDoc wipes the editor curves too, but a section reset only touches its
+    // own slice, restore curves for any alias whose custom ramp outlived it
+    // (a reset colour section drops to a stock name, so isCustomPalette filters
+    // it out) or the editor would silently refit the untouched ramp.
+    const preservedPp = JSON.parse(JSON.stringify(paletteParams.value)) as typeof paletteParams.value
+    applyDoc(keys.reduce((doc, entry) => mergeSection(doc, baselineDoc.value, entry), plain))
+    setPaletteParams(Object.fromEntries(
+      Object.entries(preservedPp).filter(([alias]) => isCustomPalette(alias))
+    ))
+    setActivePreset(preserved)
+    track('Theme Section Reset', { section: keys.join(',') })
+  }
+
+  /** For flows that replace the whole doc outside a preset (imports). */
+  function clearActivePreset() {
+    setActivePreset(undefined)
+  }
+
+  /**
+   * The preset the pickers show as selected. An untouched theme IS the stock
+   * preset, so it reads as Default rather than as nothing selected; once
+   * edits diverge with no preset behind them there's nothing to point at
+   * (the menu calls that 'Custom').
+   */
+  const selectedPreset = computed(() => {
+    if (activePreset.value) return activePreset.value
+    return (theme.hasCSSChanges.value || theme.hasConfigChanges.value) ? undefined : DEFAULT_PRESET_ID
+  })
+
+  return {
+    presets,
+    activePreset,
+    selectedPreset,
+    baselineDoc,
+    clearActivePreset,
+    sectionDirty,
+    groupDirty,
+    resetSection,
+    style,
+    setStyle,
+    paletteParams,
+    setPaletteParams,
+    isCustomPalette,
+    paletteShades,
+    selectPalette,
+    setPaletteFromCurve,
+    applyDoc,
+    applyPreset,
+    shuffle,
+    neutralChip,
+    primaryChip,
+    rampChip
+  }
+}
diff --git a/docs/app/composables/useThemeStudioHistory.ts b/docs/app/composables/useThemeStudioHistory.ts
new file mode 100644
index 0000000000..eb229e3d3e
--- /dev/null
+++ b/docs/app/composables/useThemeStudioHistory.ts
@@ -0,0 +1,144 @@
+import type { ThemeDoc, StoredPaletteParams } from '../utils/theme/engine'
+
+/**
+ * One undo/redo step. The exported `doc` carries colours, style and the
+ * RESOLVED palette shades, but not the curves and pins behind them, which
+ * live in the studio's `paletteParams`. We snapshot both: restoring the doc
+ * alone would fix the visible colours yet strand the palette editor on stale
+ * (or refitted-to-default) curves, and the next edit would regenerate from
+ * those and clobber the ramp.
+ */
+interface HistoryEntry {
+  doc: ThemeDoc
+  pp: Partial<Record<string, StoredPaletteParams>>
+}
+
+/**
+ * Undo/redo over whole theme documents, the same serialize/restore pair
+ * exports and presets already use, so one history entry is one applyDoc
+ * away. State is app-level because the site header hosts the undo/redo
+ * buttons while on /theme; the page owns the debounced capture watcher.
+ * Session-only by design.
+ */
+export function useThemeStudioHistory() {
+  const { applyDoc, paletteParams, setPaletteParams } = useThemeStudio()
+  const { currentDoc } = useTheme()
+
+  const past = useState<HistoryEntry[]>('theme-studio-history-past', () => [])
+  const future = useState<HistoryEntry[]>('theme-studio-history-future', () => [])
+  const lastSnapshot = useState('theme-studio-history-snapshot', () => '')
+  const pendingRestore = useState('theme-studio-history-pending', () => false)
+
+  /**
+   * The full restorable studio state as a stable string, the exported doc
+   * plus the editor's curve/pin params. Reads reactive sources, so the page's
+   * capture watcher re-runs on any change to either.
+   */
+  function snapshot() {
+    return JSON.stringify({ doc: currentDoc(), pp: paletteParams.value })
+  }
+
+  /**
+   * Realign the baseline without recording (page mount). If the theme
+   * changed while no watcher was mounted (preset from the header picker on
+   * another page), the stacks describe a document lineage that no longer
+   * exists, undo/redo against them would clobber the off-page change, so
+   * they reset.
+   */
+  function align(snap: string) {
+    if (lastSnapshot.value && snap !== lastSnapshot.value) {
+      past.value = []
+      future.value = []
+    }
+    pendingRestore.value = false
+    lastSnapshot.value = snap
+  }
+
+  /** Record a settled snapshot (call after the page's debounce). */
+  function capture(snap: string) {
+    if (pendingRestore.value) {
+      // the first settle after our own undo/redo restore, realign without
+      // recording, however long the flush took
+      pendingRestore.value = false
+      lastSnapshot.value = snap
+      return
+    }
+    if (snap === lastSnapshot.value) return
+    // No baseline yet (capture before the page's mount align), adopt
+    // rather than record: JSON.parse('') would throw.
+    if (!lastSnapshot.value) {
+      lastSnapshot.value = snap
+      return
+    }
+    past.value.push(JSON.parse(lastSnapshot.value))
+    if (past.value.length > 50) past.value.shift()
+    future.value = []
+    lastSnapshot.value = snap
+  }
+
+  function restore(entry: HistoryEntry) {
+    pendingRestore.value = true
+    // The baseline moves NOW, not at the debounced settle, a second
+    // undo/redo inside the debounce window must push this entry, not the
+    // pre-restore state (which would drop a step and duplicate another).
+    lastSnapshot.value = JSON.stringify(entry)
+    applyDoc(entry.doc)
+    // Restore the editor curves/pins AFTER applyDoc, applyDoc resets and
+    // re-applies the visible colours (and clears paletteParams), so this must
+    // run last to realign the editor's source of truth to the restored ramp.
+    // JSON round-trip, NOT structuredClone: entry.pp is a reactive-proxy value
+    // off the history useState, and structuredClone throws DataCloneError on a
+    // Vue Proxy, which would abort restore right before this line, leaving the
+    // ramp applied but the editor stranded on stale curves.
+    setPaletteParams(entry.pp ? JSON.parse(JSON.stringify(entry.pp)) : {})
+    // the settle still realigns from snapshot() itself, the applied doc
+    // may re-serialize differently than it round-trips
+  }
+
+  function undo() {
+    const entry = past.value.pop()
+    if (!entry) return
+    future.value.push(JSON.parse(lastSnapshot.value))
+    restore(entry)
+  }
+
+  function redo() {
+    const entry = future.value.pop()
+    if (!entry) return
+    past.value.push(JSON.parse(lastSnapshot.value))
+    restore(entry)
+  }
+
+  return { past, future, snapshot, align, capture, undo, redo }
+}
+
+/**
+ * Drives the history stack from the live theme: aligns the baseline on mount,
+ * then folds every burst of edits into one step. Slider drags fire per pixel,
+ * so a raw watcher would record a step per frame.
+ */
+export function useThemeStudioRecorder() {
+  const { snapshot, align, capture } = useThemeStudioHistory()
+
+  const mounted = ref(false)
+  let timeout: ReturnType<typeof setTimeout> | undefined
+
+  onMounted(() => {
+    mounted.value = true
+    align(snapshot())
+  })
+
+  // the snapshot spans the doc AND the editor's curve/pin params
+  watch(() => (mounted.value ? snapshot() : undefined), (snap) => {
+    if (!snap) return
+    clearTimeout(timeout)
+    timeout = setTimeout(() => capture(snap), 350)
+  })
+
+  // A pending capture flushes rather than dies, an edit inside the debounce
+  // window would otherwise vanish from history.
+  onUnmounted(() => {
+    clearTimeout(timeout)
+    capture(snapshot())
+  })
+}
diff --git a/docs/app/composables/useThemeStudioToolbar.ts b/docs/app/composables/useThemeStudioToolbar.ts
new file mode 100644
index 0000000000..fe032695e5
--- /dev/null
+++ b/docs/app/composables/useThemeStudioToolbar.ts
@@ -0,0 +1,75 @@
+import { DEFAULT_PRESET_ID } from '../utils/theme/engine'
+import { paletteLabel } from '../utils/theme/studio'
+
+/**
+ * What the toolbar reports and what its reset does. The persisted theme is
+ * client-only, so everything derived from it is gated on mount, hydration
+ * adopts SSR attributes without patching, and a disabled= adopted at hydration
+ * would never lift.
+ */
+export function useThemeStudioToolbar() {
+  const { resetTheme, primary, neutral, blackAsPrimary } = useTheme()
+  const { groupDirty, sectionDirty, presets, activePreset, applyPreset, primaryChip, neutralChip, isCustomPalette } = useThemeStudio()
+
+  const mounted = ref(false)
+  onMounted(() => (mounted.value = true))
+
+  // A custom ramp has no name worth reading, the picker calls it Custom too.
+  function paletteName(alias: 'primary' | 'neutral', value: string) {
+    return isCustomPalette(alias) ? 'Custom' : capitalize(paletteLabel(value))
+  }
+
+  /** The two colours the panel owns, so the bar reports them unopened. */
+  const colorChips = computed(() => [{
+    dot: blackAsPrimary.value ? undefined : `var(--color-${primaryChip.value}-500)`,
+    label: blackAsPrimary.value ? 'Black' : paletteName('primary', primary.value)
+  }, {
+    dot: `var(--color-${neutralChip.value}-500)`,
+    label: paletteName('neutral', neutral.value)
+  }])
+
+  const colorLabel = computed(() => colorChips.value.map(chip => chip.label).join(', '))
+
+  /**
+   * "Changed from preset" per toolbar control. Type, icons and radius sit in
+   * the bar on their own now, so they are listed here rather than rolled into
+   * a group: `anyDirty` below folds over this object, and a section left out
+   * of it would leave the reset button dead after a real change.
+   *
+   * Gated on mount like everything else here. The theme plugin restores the
+   * saved doc BEFORE the root component's setup, so an ungated flag is
+   * already true on the client's first render while the server rendered it
+   * false; hydration adopts the server's markup without patching, and the
+   * control would sit un-highlighted until something else forced a re-render.
+   */
+  const afterMount = (source: ComputedRef<boolean>) => computed(() => mounted.value && source.value)
+
+  const groupDirtyFlags = {
+    colors: afterMount(groupDirty('colors')),
+    defaults: afterMount(groupDirty('defaults')),
+    font: afterMount(sectionDirty('font')),
+    icons: afterMount(sectionDirty('icons')),
+    radius: afterMount(sectionDirty('radius'))
+  }
+
+  // Two-stage reset: edits reset back to the preset, a second press clears
+  // the preset back to stock.
+  const anyDirty = computed(() => mounted.value && Object.values(groupDirtyFlags).some(flag => flag.value))
+  const baselinePreset = computed(() => (mounted.value ? presets.find(preset => preset.id === activePreset.value) : undefined))
+  const resetsToPreset = computed(() => Boolean(baselinePreset.value) && anyDirty.value)
+  const canReset = computed(() => anyDirty.value || Boolean(baselinePreset.value))
+  // named from the preset itself, so a rename can't leave this behind
+  const stockPreset = computed(() => presets.find(preset => preset.id === DEFAULT_PRESET_ID))
+
+  const resetLabel = computed(() => {
+    if (resetsToPreset.value) return `Reset to ${baselinePreset.value!.name}`
+    return baselinePreset.value ? `Reset to ${stockPreset.value?.name ?? 'stock'} theme` : 'Reset theme'
+  })
+
+  function resetToBaseline() {
+    if (resetsToPreset.value) applyPreset(baselinePreset.value!)
+    else resetTheme()
+  }
+
+  return { colorChips, colorLabel, groupDirtyFlags, canReset, resetLabel, resetToBaseline }
+}
diff --git a/docs/app/composables/useThemeStudioView.ts b/docs/app/composables/useThemeStudioView.ts
new file mode 100644
index 0000000000..52fddfaff5
--- /dev/null
+++ b/docs/app/composables/useThemeStudioView.ts
@@ -0,0 +1,88 @@
+import type { ThemeIcons } from '../utils/theme/icons'
+
+export type ThemeStudioView = 'grid' | 'dashboard' | 'chat' | 'saas' | 'landing' | 'docs' | 'portfolio' | 'changelog' | 'editor' | 'a11y'
+
+export interface ThemeStudioViewTab {
+  label: string
+  icon: string
+  value: ThemeStudioView
+  /** One-liner for the rich switcher, template blurbs from /templates. */
+  description: string
+  /** /templates screenshot base path (`-light.png`/`-dark.png` appended); grid and a11y are studio-only and have none. */
+  image?: string
+}
+
+const templateImage = (name: string) => `/assets/templates/nuxt/${name}`
+
+export const THEME_STUDIO_VIEWS: ThemeStudioViewTab[] = [
+  { label: 'Components', icon: 'i-lucide-layout-grid', value: 'grid', description: 'Every themed component at a glance, the component wall.' },
+  { label: 'Dashboard', icon: 'i-lucide-layout-dashboard', value: 'dashboard', description: 'Multi-column admin interface with multiple views.', image: templateImage('dashboard') },
+  { label: 'Chat', icon: 'i-lucide-message-circle', value: 'chat', description: 'An AI chatbot with sidebar history and streaming replies.', image: templateImage('chat') },
+  { label: 'SaaS', icon: 'i-lucide-rocket', value: 'saas', description: 'A SaaS home with hero, pricing and feature sections.', image: templateImage('saas') },
+  { label: 'Landing', icon: 'i-lucide-panels-top-left', value: 'landing', description: 'A modern marketing landing page.', image: templateImage('landing') },
+  { label: 'Docs', icon: 'i-lucide-book-open', value: 'docs', description: 'Navigation, prose, code and TOC.', image: templateImage('docs') },
+  { label: 'Portfolio', icon: 'i-lucide-user-round', value: 'portfolio', description: 'A personal portfolio with work, blog and testimonials.', image: templateImage('portfolio') },
+  { label: 'Changelog', icon: 'i-lucide-newspaper', value: 'changelog', description: 'Release notes with sticky intro and version timeline.', image: templateImage('changelog') },
+  { label: 'Editor', icon: 'i-lucide-file-pen-line', value: 'editor', description: 'A rich text editor with toolbar, slash menu and drag handles.', image: templateImage('editor') },
+  { label: 'A11y', icon: 'i-lucide-accessibility', value: 'a11y', description: 'Contrast matrix for every token pair in the theme.' }
+]
+
+/**
+ * Per-pack overrides for the view-switcher glyphs, so the switcher skins to
+ * the applied theme like the rest of the studio chrome. A view falls back to
+ * its Lucide default (THEME_STUDIO_VIEWS) wherever the active pack has no
+ * entry. Only pixelarticons is curated today; other packs keep Lucide until
+ * filled in. Pixel has no rocket/panels/newspaper/accessibility glyphs, so
+ * SaaS→zap, Landing→layout, Changelog→article and A11y→human stand in.
+ */
+const studioViewIcons: Partial<Record<ThemeIcons, Partial<Record<ThemeStudioView, string>>>> = {
+  pixelarticons: {
+    grid: 'i-pixelarticons-dashboard',
+    dashboard: 'i-pixelarticons-dashboard',
+    chat: 'i-pixelarticons-message',
+    saas: 'i-pixelarticons-zap',
+    landing: 'i-pixelarticons-layout',
+    docs: 'i-pixelarticons-book-open',
+    portfolio: 'i-pixelarticons-user',
+    changelog: 'i-pixelarticons-article',
+    editor: 'i-pixelarticons-edit-box',
+    a11y: 'i-pixelarticons-human'
+  }
+}
+
+/** The studio's preview state, shared by the page and its toolbar. */
+export function useThemeStudioView() {
+  const view = useState<ThemeStudioView>('theme-studio-view', () => 'grid')
+
+  return { view, views: THEME_STUDIO_VIEWS }
+}
+
+/** The view glyphs resolved for the active icon pack (override ?? Lucide). */
+export function useStudioViewIcons() {
+  const { icon } = useTheme()
+  return computed(() => {
+    const overrides = studioViewIcons[icon.value as ThemeIcons] ?? {}
+    return Object.fromEntries(
+      THEME_STUDIO_VIEWS.map(tab => [tab.value, overrides[tab.value] ?? tab.icon])
+    ) as Record<ThemeStudioView, string>
+  })
+}
+
+/**
+ * Mirrors the preview into ?view=, so a reload (or a shared link) lands on the
+ * same page. Read during setup rather than on mount: the server renders the
+ * requested view, and hydration has nothing to correct.
+ */
+export function useThemeStudioViewParam() {
+  const { view, views } = useThemeStudioView()
+  const route = useRoute()
+  const router = useRouter()
+
+  const requested = route.query.view
+  if (typeof requested === 'string' && views.some(tab => tab.value === requested)) {
+    view.value = requested as ThemeStudioView
+  }
+
+  // grid is the default, so it stays out of the URL
+  watch(view, value => router.replace({ query: { ...route.query, view: value === 'grid' ? undefined : value } }))
+}
diff --git a/docs/app/composables/useTokenShades.ts b/docs/app/composables/useTokenShades.ts
new file mode 100644
index 0000000000..c7ebe12838
--- /dev/null
+++ b/docs/app/composables/useTokenShades.ts
@@ -0,0 +1,68 @@
+import { TOKEN_SHADE_TARGETS, SHADE_LADDER, SHADE_LADDERS, storedStopStep, canonicalTokenShades } from '../utils/theme/engine'
+import type { ColorAlias, ShadeStop } from '../utils/theme/engine'
+
+/**
+ * Per-mode shade sliders for the semantic tokens riding one ramp, the accent
+ * pair for a color alias, every neutral-ramped token for neutral. Shared by
+ * the Colors panel section and the folded token groups.
+ */
+export function useTokenShades(alias: ColorAlias) {
+  const { style, setStyle, baselineDoc, isCustomPalette, paletteParams } = useThemeStudio()
+
+  /** The active preset's own shade choices, what a row reset restores. */
+  const baselineShades = computed(() => canonicalTokenShades(baselineDoc.value))
+
+  // A custom palette's tokens can pick every stop its density emits, the
+  // sliders (and their model mapping) span that ladder, up to 91 stops. Stock
+  // ramps only define the standard 11, so they stay on the short ladder.
+  const shadeLadder = computed<readonly ShadeStop[]>(() => (isCustomPalette(alias)
+    ? SHADE_LADDERS[storedStopStep(paletteParams.value[alias])]
+    : SHADE_LADDER))
+
+  // Only the touched mode is written, so an untouched mode never becomes an
+  // override. Reset restores the BASELINE preset's shade, or deletes the entry
+  // when the preset made no choice, a token's real default may not sit on the
+  // ramp at all (--ui-bg is literally `white`).
+  function control(token: string, defaults: { light: ShadeStop, dark: ShadeStop }, target: 'light' | 'dark') {
+    const model = computed({
+      get: () => {
+        const value = style.value.tokenShades?.[token]?.[target] ?? defaults[target]
+        // a stop coarsened off the ladder reads indexOf -1, clamp so the
+        // slider stays grabbable
+        return Math.max(0, shadeLadder.value.indexOf(value as ShadeStop))
+      },
+      set: (index: number) => {
+        setStyle({
+          tokenShades: {
+            ...style.value.tokenShades,
+            [token]: { ...style.value.tokenShades?.[token], [target]: shadeLadder.value[index]! }
+          }
+        })
+      }
+    })
+    const baseline = computed(() => baselineShades.value[token]?.[target])
+    const dirty = computed(() => style.value.tokenShades?.[token]?.[target] !== baseline.value)
+    function reset() {
+      const entry: { light?: ShadeStop, dark?: ShadeStop } = { ...style.value.tokenShades?.[token] }
+      if (baseline.value !== undefined) entry[target] = baseline.value
+      else Reflect.deleteProperty(entry, target)
+      const tokenShades = { ...style.value.tokenShades }
+      if (Object.keys(entry).length) tokenShades[token] = entry
+      else Reflect.deleteProperty(tokenShades, token)
+      setStyle({ tokenShades })
+    }
+    return { model, dirty, reset }
+  }
+
+  const sections = TOKEN_SHADE_TARGETS
+    .filter(target => alias === 'neutral' ? target.ramp === 'neutral' : target.token === `--ui-${alias}`)
+    .map(target => ({
+      ...target,
+      sliders: {
+        light: control(target.token, target.defaults, 'light'),
+        dark: control(target.token, target.defaults, 'dark')
+      }
+    }))
+
+  return { shadeLadder, sections }
+}
diff --git a/docs/app/pages/theme.vue b/docs/app/pages/theme.vue
new file mode 100644
index 0000000000..a43cf38951
--- /dev/null
+++ b/docs/app/pages/theme.vue
@@ -0,0 +1,201 @@
+<script setup lang="ts">
+const { track } = useAnalytics()
+const { icon: iconSet, font } = useTheme()
+
+// Toolbar skins to the applied icon pack; import/chevron reuse the standard
+// semantic keys off appConfig.ui.icons.
+const studioIcons = useStudioIcons()
+const appConfig = useAppConfig()
+
+const { view } = useThemeStudioView()
+const { past, future, undo, redo } = useThemeStudioHistory()
+const { colorChips, colorLabel, groupDirtyFlags, canReset, resetLabel, resetToBaseline } = useThemeStudioToolbar()
+
+useThemeStudioRecorder()
+useThemeStudioViewParam()
+
+// The studio's preview is a card floating on a recessed canvas, which is the
+// one background the semantic tokens can't express: `--ui-bg-*` only ever
+// elevates, so there is no "behind the surface" step (v5's elevation ladder).
+// Unhead drops the class on navigate, so the canvas stays on this page.
+useHead({
+  bodyAttrs: { class: 'theme-studio' }
+})
+
+useSeoMeta({
+  titleTemplate: '%s - Nuxt UI',
+  title: 'Theme Studio',
+  description: 'Customize Nuxt UI live: colors, radius, fonts and icons, then export only what you changed.'
+})
+
+onMounted(() => track('Theme Studio Opened'))
+
+// Color mode rides the app-wide `d` binding in app.vue, no page copy needed.
+defineShortcuts({
+  meta_z: undo,
+  meta_shift_z: redo,
+  ctrl_y: redo
+})
+
+const openPanels = reactive({ presets: false, colors: false, font: false, icons: false, radius: false, style: false, view: false })
+
+/** The shared import/export modal, the two toolbar buttons pick its mode. */
+const shareOpen = ref(false)
+const shareMode = ref<'import' | 'export'>('export')
+</script>
+
+<template>
+  <!-- page tint composites on the app root's bg-default (nuxt.config rootAttrs) -->
+  <main class="max-w-(--ui-container) mx-auto">
+    <UHeader :ui="{ root: () => 'h-(--ui-header-height)' }">
+      <template #left>
+        <HeaderLogo />
+      </template>
+
+      <ThemeStudioViewSwitcher v-model:open="openPanels.view" :content="{ align: 'end' }" variant="outline" />
+    </UHeader>
+
+    <div class="flex flex-col w-full bg-default rounded-xl overflow-hidden shadow ring ring-default h-[calc(100dvh-var(--ui-header-height)-var(--ui-header-height))]">
+      <!-- [contain:paint]: Chromium won't clip nested composited layers by
+             an ancestor's overflow alone. Keyed on the icon pack: demo views
+             resolve icons at setup, so a pack swap remounts to re-resolve. -->
+      <div :key="iconSet" class="flex-1 min-h-0 overflow-hidden *:contain-[paint]">
+        <Playground v-if="view === 'grid'" />
+        <LazyThemeStudioViewDashboard v-else-if="view === 'dashboard'" />
+        <LazyThemeStudioViewChat v-else-if="view === 'chat'" />
+        <LazyThemeStudioViewSaas v-else-if="view === 'saas'" />
+        <LazyThemeStudioViewLanding v-else-if="view === 'landing'" />
+        <LazyThemeStudioViewDocs v-else-if="view === 'docs'" />
+        <LazyThemeStudioViewPortfolio v-else-if="view === 'portfolio'" />
+        <LazyThemeStudioViewChangelog v-else-if="view === 'changelog'" />
+        <LazyThemeStudioViewEditor v-else-if="view === 'editor'" />
+        <LazyThemeStudioViewA11y v-else-if="view === 'a11y'" />
+      </div>
+    </div>
+
+    <UFooter>
+      <template #left>
+        <ThemeStudioToolbarField v-slot="{ tooltip }" label="Preset">
+          <ThemeStudioPresetMenu v-model:open="openPanels.presets" keep-panels :tooltip="tooltip" class="w-38" />
+        </ThemeStudioToolbarField>
+
+        <ThemeStudioToolbarPopover
+          v-model:open="openPanels.colors"
+          label="Colors"
+          :value="colorLabel"
+          :dirty="groupDirtyFlags.colors.value"
+        >
+          <template #leading>
+            <span class="flex items-center -space-x-0.5">
+              <!-- primary stacks on top; black-as-primary has no ramp
+                       variable to point at -->
+              <span
+                v-for="(chip, index) in colorChips"
+                :key="chip.label"
+                class="relative size-3 rounded-full ring-2 ring-(--ui-bg-elevated)"
+                :class="!chip.dot && 'bg-black dark:bg-white'"
+                :style="{ ...(chip.dot ? { backgroundColor: chip.dot } : {}), zIndex: colorChips.length - index }"
+              />
+            </span>
+          </template>
+
+          <ThemeStudioControls group="colors" class="w-80 max-h-[70vh] overflow-y-auto" />
+        </ThemeStudioToolbarPopover>
+
+        <ThemeStudioToolbarPopover
+          v-model:open="openPanels.font"
+          label="Text"
+          :icon="studioIcons.text"
+          :value="font"
+          :dirty="groupDirtyFlags.font.value"
+        >
+          <ThemeStudioFontOptions />
+        </ThemeStudioToolbarPopover>
+
+        <!-- the picker is already a popover, so it sits in the bar directly
+                 rather than inside a second one -->
+        <ThemeStudioToolbarField v-slot="{ tooltip }" label="Icons">
+          <ThemeStudioIconOptions v-model:open="openPanels.icons" :tooltip="tooltip" :dirty="groupDirtyFlags.icons.value" class="w-38" />
+        </ThemeStudioToolbarField>
+
+        <ThemeStudioToolbarField v-slot="{ tooltip }" label="Radius">
+          <ThemeStudioRadiusOptions v-model:open="openPanels.radius" :tooltip="tooltip" :dirty="groupDirtyFlags.radius.value" class="w-30" />
+        </ThemeStudioToolbarField>
+
+        <ThemeStudioToolbarPopover
+          v-model:open="openPanels.style"
+          label="Defaults"
+          :icon="studioIcons.options"
+          :dirty="groupDirtyFlags.defaults.value"
+        >
+          <ThemeStudioControls group="style" class="w-80 max-h-[70vh] overflow-y-auto" />
+        </ThemeStudioToolbarPopover>
+      </template>
+
+      <template #right>
+        <UTooltip text="Color mode" :kbds="['d']">
+          <UColorModeButton color="neutral" variant="outline" data-keep-panels class="shrink-0" />
+        </UTooltip>
+
+        <ThemeStudioShuffleButton />
+
+        <UFieldGroup class="shrink-0">
+          <UTooltip text="Undo" :kbds="['meta', 'Z']">
+            <UButton
+              :icon="studioIcons.undo"
+              color="neutral"
+              variant="outline"
+              :disabled="!past.length"
+              aria-label="Undo theme change"
+              @click="undo"
+            />
+          </UTooltip>
+
+          <UTooltip text="Redo" :kbds="['meta', 'shift', 'Z']">
+            <UButton
+              :icon="studioIcons.redo"
+              color="neutral"
+              variant="outline"
+              :disabled="!future.length"
+              aria-label="Redo theme change"
+              @click="redo"
+            />
+          </UTooltip>
+        </UFieldGroup>
+
+        <UTooltip :text="resetLabel">
+          <UButton
+            :icon="studioIcons.reset"
+            color="neutral"
+            variant="outline"
+            :disabled="!canReset"
+            :aria-label="resetLabel"
+            @click="resetToBaseline"
+          />
+        </UTooltip>
+
+        <UFieldGroup>
+          <UTooltip text="Import theme">
+            <UButton
+              :icon="appConfig.ui.icons.upload"
+              color="neutral"
+              variant="outline"
+              aria-label="Import theme"
+              @click="shareMode = 'import'; shareOpen = true"
+            />
+          </UTooltip>
+
+          <UButton
+            label="Export"
+            :icon="studioIcons.export"
+            color="neutral"
+            variant="outline"
+            @click="shareMode = 'export'; shareOpen = true"
+          />
+        </UFieldGroup>
+      </template>
+    </UFooter>
+
+    <ThemeStudioShareModal v-model:open="shareOpen" v-model:mode="shareMode" />
+  </main>
+</template>
diff --git a/docs/app/plugins/theme.ts b/docs/app/plugins/theme.ts
index a996cdbadd..4f5af62809 100644
--- a/docs/app/plugins/theme.ts
+++ b/docs/app/plugins/theme.ts
@@ -1,5 +1,9 @@
 import { defu } from 'defu'
-import { themeIcons, cssVariableDefaults } from '../utils/theme'
+import { themeIcons } from '../utils/theme/icons'
+import { cssVariableDefaults } from '../utils/theme/tokens'
+import { THEME_STATE_KEYS, readStoredTheme, writeStoredTheme } from '../utils/theme/storage'
+import type { StoredTheme } from '../utils/theme/storage'
+import { mergeUi, styleComponents, DEFAULT_COLORS, THEME_DEFAULTS } from '../utils/theme/engine'
 
 export default defineNuxtPlugin({
   enforce: 'post',
@@ -7,185 +11,213 @@ export default defineNuxtPlugin({
     const appConfig = useAppConfig()
 
     if (import.meta.client) {
-      const primary = localStorage.getItem('nuxt-ui-primary')
-      if (primary) appConfig.ui.colors.primary = primary
+      const saved = readStoredTheme()
 
-      const neutral = localStorage.getItem('nuxt-ui-neutral')
-      if (neutral) appConfig.ui.colors.neutral = neutral
-
-      const icons = localStorage.getItem('nuxt-ui-icons')
-      if (icons) appConfig.ui.icons = themeIcons[icons as keyof typeof themeIcons] as any
-
-      function restoreState<T>(key: string) {
-        try {
-          const raw = localStorage.getItem(key)
-          if (raw) {
-            const state = useState<T>(key)
-            state.value = JSON.parse(raw)
-          }
-        } catch {
-          // ignore malformed localStorage
+      // Assign, never seed. This plugin runs before the root component's
+      // setup, but AFTER the SSR payload is hydrated, so every useState key
+      // below already holds the server's default and its initializer will
+      // not re-run. Writing the values here is what makes a saved theme
+      // survive a reload.
+      const assign = <T>(key: string, value: T | undefined) => {
+        if (value !== undefined) useState<T>(key).value = value
+      }
+      assign('nuxt-ui-radius', saved.radius)
+      assign('nuxt-ui-font-size', saved.fontSize)
+      assign('nuxt-ui-font', saved.font)
+      assign('nuxt-ui-icons', saved.icons)
+      assign('nuxt-ui-black-as-primary', saved.blackAsPrimary)
+      assign('nuxt-ui-custom-colors', saved.customColors)
+      assign('nuxt-ui-css-variables', saved.cssVariables)
+      assign(THEME_STATE_KEYS.stylePrefs, saved.style)
+      assign(THEME_STATE_KEYS.paletteParams, saved.paletteParams)
+      assign(THEME_STATE_KEYS.themePreset, saved.preset)
+      if (saved.colors || saved.components) {
+        useState<Record<string, any>>('nuxt-ui-ai-theme').value = {
+          ...(saved.colors ? { colors: { ...saved.colors } } : {}),
+          ...(saved.components ? { ui: { ...saved.components } } : {})
         }
       }
 
-      restoreState('nuxt-ui-ai-theme')
-      restoreState('nuxt-ui-custom-colors')
-      restoreState('nuxt-ui-css-variables')
+      // Same distribution order the per-key restores used, which carries two
+      // fixes worth keeping. Colors land now, before hydration, because their
+      // FOUC scripts already rewrote the style tags before first paint. Icons
+      // land AFTER: icon names compile into element CLASSES and Vue only warns
+      // about a class that disagrees with the server, it never patches it, so
+      // assigning pre-hydration silently dropped the saved pack every reload.
+      if (saved.primary) appConfig.ui.colors.primary = saved.primary
+      if (saved.neutral) appConfig.ui.colors.neutral = saved.neutral
+      for (const [alias, name] of Object.entries(saved.colors || {})) {
+        (appConfig.ui.colors as any)[alias] = name
+      }
+
+      const pack = saved.icons ? themeIcons[saved.icons as keyof typeof themeIcons] : undefined
+      if (pack) onNuxtReady(() => (appConfig.ui.icons = pack as any))
 
-      try {
-        const extras = JSON.parse(localStorage.getItem('nuxt-ui-ai-theme') || '{}')
-        if (extras.colors) {
-          for (const [key, value] of Object.entries(extras.colors)) {
-            (appConfig.ui.colors as any)[key] = value
+      // The class bundle is DERIVED from the style prefs, so it is rebuilt
+      // here rather than stored. A generator change therefore reaches
+      // already-saved themes instead of serving a frozen bundle.
+      const styleUi = saved.style ? styleComponents(saved.style) : {}
+      if (Object.keys(styleUi).length || saved.components) {
+        useState<Record<string, any>>('nuxt-ui-style-ui').value = styleUi
+        onNuxtReady(() => {
+          // same order as the live path: style bundle first, explicit wins
+          const merged = mergeUi(styleUi, saved.components || {})
+          for (const [key, value] of Object.entries(merged)) {
+            if (key === 'colors' || key === 'icons') continue
+            (appConfig.ui as any)[key] = defu(value as Record<string, any>, (appConfig.ui as any)[key] || {})
           }
-        }
-        if (extras.ui) {
-          onNuxtReady(() => {
-            for (const [key, value] of Object.entries(extras.ui)) {
-              if (key === 'colors' || key === 'icons') continue
-              (appConfig.ui as any)[key] = defu(value as Record<string, any>, (appConfig.ui as any)[key] || {})
-            }
-          })
-        }
-      } catch {
-        // ignore malformed localStorage
+        })
       }
+
+      // One watcher owns every write. Each setting used to persist itself, so
+      // a reload could restore them out of step and the derived stores needed
+      // self-heals to reconcile; one atomic write makes that impossible.
+      //
+      // Reads the raw state refs rather than `currentDoc()`: the doc is diffed
+      // against a stock library install on every call, which is far too much
+      // work for a watcher that fires on every slider frame, and calling
+      // `useTheme()` outside a component would fire its onMounted with no
+      // instance. Defaults are omitted so an untouched theme stores nothing.
+      const radius = useState<number>('nuxt-ui-radius')
+      const fontSize = useState<number>('nuxt-ui-font-size')
+      const font = useState<StoredTheme['font']>('nuxt-ui-font')
+      const iconSet = useState<string>('nuxt-ui-icons')
+      const blackAsPrimary = useState<boolean>('nuxt-ui-black-as-primary')
+      const style = useState<StoredTheme['style']>(THEME_STATE_KEYS.stylePrefs)
+      const paletteParams = useState<StoredTheme['paletteParams']>(THEME_STATE_KEYS.paletteParams)
+      const preset = useState<string | undefined>(THEME_STATE_KEYS.themePreset)
+      const extras = useState<Record<string, any>>('nuxt-ui-ai-theme')
+      const customColors = useState<StoredTheme['customColors']>('nuxt-ui-custom-colors')
+      const cssVariables = useState<StoredTheme['cssVariables']>('nuxt-ui-css-variables')
+
+      const filled = <T extends object>(value: T | undefined) => value && Object.keys(value).length ? value : undefined
+      const unless = <T>(value: T, fallback: T) => value === fallback ? undefined : value
+
+      watch(() => JSON.stringify({
+        primary: unless(appConfig.ui.colors.primary, DEFAULT_COLORS.primary),
+        neutral: unless(appConfig.ui.colors.neutral, DEFAULT_COLORS.neutral),
+        radius: unless(radius.value, THEME_DEFAULTS.radius),
+        fontSize: unless(fontSize.value, THEME_DEFAULTS.fontSize),
+        font: filled(font.value),
+        icons: unless(iconSet.value, THEME_DEFAULTS.icons),
+        blackAsPrimary: blackAsPrimary.value || undefined,
+        colors: filled(extras.value?.colors),
+        components: filled(extras.value?.ui),
+        customColors: filled(customColors.value),
+        cssVariables: filled(cssVariables.value?.light) || filled(cssVariables.value?.dark) ? cssVariables.value : undefined,
+        style: filled(style.value),
+        paletteParams: filled(paletteParams.value),
+        preset: preset.value
+      } satisfies StoredTheme), json => writeStoredTheme(JSON.parse(json)), { flush: 'post' })
     }
 
     if (import.meta.server) {
-      // Inline scripts below intentionally duplicate logic from the client-side composable
-      // (useTheme / injectCustomColors / injectCSSVariables) to restore persisted theme
-      // settings on first paint and prevent a flash of unstyled content (FOUC).
-      // The script IDs (chat-custom-colors, chat-css-variables, nuxt-ui-radius, etc.)
-      // correspond to the <style> elements managed by useTheme via useHead.
+      // One FOUC script over the one storage key. Every setting used to ship
+      // its own inline script re-reading its own key, eight of them, each
+      // duplicating a slice of useTheme's reactive style tags. This still
+      // duplicates the derivations (it has to run before paint, before any
+      // Vue code exists) but it parses once and writes every tag in order.
       useHead({
         script: [{
           innerHTML: `
             (function() {
-              var primaryColor = localStorage.getItem('nuxt-ui-primary');
-              var neutralColor = localStorage.getItem('nuxt-ui-neutral');
-              if (!primaryColor && !neutralColor) return;
-              function swapColors(el) {
-                var html = el.innerHTML;
-                if (primaryColor && primaryColor !== 'black') {
-                  html = html.replace(
-                    /(--ui-color-primary-\\d{2,3}:\\s*var\\(--color-)${appConfig.ui.colors.primary}(-\\d{2,3}.*?\\))/g,
-                    \`$1\${primaryColor}$2\`
-                  );
-                }
-                if (neutralColor) {
-                  html = html.replace(
-                    /(--ui-color-neutral-\\d{2,3}:\\s*var\\(--color-)${appConfig.ui.colors.neutral}(-\\d{2,3}.*?\\))/g,
-                    \`$1\${neutralColor === 'neutral' ? 'old-neutral' : neutralColor}$2\`
-                  );
-                }
-                el.innerHTML = html;
-              }
-              var colorsEl = document.querySelector('style#nuxt-ui-colors');
-              if (colorsEl) {
-                swapColors(colorsEl);
-              } else {
-                var obs = new MutationObserver(function(mutations) {
-                  for (var i = 0; i < mutations.length; i++) {
-                    for (var j = 0; j < mutations[i].addedNodes.length; j++) {
-                      var node = mutations[i].addedNodes[j];
-                      if (node.id === 'nuxt-ui-colors') {
-                        swapColors(node);
-                        obs.disconnect();
-                        return;
+              var T = {};
+              try { T = JSON.parse(localStorage.getItem('nuxt-ui-theme') || '{}') || {}; } catch (e) { return; }
+              var SAFE = /^[\\w -]{1,50}$/;
+              function num(v, lo, hi) { var n = parseFloat(v); return isFinite(n) ? Math.min(hi, Math.max(lo, n)) : undefined; }
+              function set(id, css) { var el = document.getElementById(id); if (el) { el.textContent = css; } }
+
+              var primaryColor = T.primary;
+              var neutralColor = T.neutral;
+              if (primaryColor || neutralColor) {
+                var swapColors = function(el) {
+                  var html = el.innerHTML;
+                  if (primaryColor && primaryColor !== 'black') {
+                    html = html.replace(/(--ui-color-primary-\\d{2,3}:\\s*var\\(--color-)${appConfig.ui.colors.primary}(-\\d{2,3}.*?\\))/g, '$1' + primaryColor + '$2');
+                  }
+                  if (neutralColor) {
+                    html = html.replace(/(--ui-color-neutral-\\d{2,3}:\\s*var\\(--color-)${appConfig.ui.colors.neutral}(-\\d{2,3}.*?\\))/g, '$1' + (neutralColor === 'neutral' ? 'old-neutral' : neutralColor) + '$2');
+                  }
+                  el.innerHTML = html;
+                };
+                var colorsEl = document.querySelector('style#nuxt-ui-colors');
+                if (colorsEl) { swapColors(colorsEl); }
+                else {
+                  var obs = new MutationObserver(function(mutations) {
+                    for (var i = 0; i < mutations.length; i++) {
+                      for (var j = 0; j < mutations[i].addedNodes.length; j++) {
+                        var node = mutations[i].addedNodes[j];
+                        if (node.id === 'nuxt-ui-colors') { swapColors(node); obs.disconnect(); return; }
                       }
                     }
-                  }
-                });
-                obs.observe(document.head, { childList: true });
-              }
-            })();
-            `.replace(/\s+/g, ' '),
-          type: 'text/javascript',
-          tagPriority: -1
-        }, {
-          innerHTML: `
-            if (localStorage.getItem('nuxt-ui-radius')) {
-              var el = document.querySelector('style#nuxt-ui-radius');
-              if (el) { el.innerHTML = ':root { --ui-radius: ' + localStorage.getItem('nuxt-ui-radius') + 'rem; }'; }
-            }
-          `.replace(/\s+/g, ' '),
-          type: 'text/javascript',
-          tagPriority: -1
-        }, {
-          innerHTML: `
-            var bapEl = document.querySelector('style#nuxt-ui-black-as-primary');
-            if (bapEl) {
-              if (localStorage.getItem('nuxt-ui-black-as-primary') === 'true') {
-                bapEl.innerHTML = ':root { --ui-primary: black; } .dark { --ui-primary: white; }';
-              } else {
-                bapEl.innerHTML = '';
+                  });
+                  obs.observe(document.head, { childList: true });
+                }
               }
-            }
-          `.replace(/\s+/g, ' ')
-        }, {
-          innerHTML: [
-            `if (localStorage.getItem('nuxt-ui-font')) {`,
-            `var font = localStorage.getItem('nuxt-ui-font');`,
-            `var fontEl = document.querySelector('style#nuxt-ui-font');`,
-            `if (fontEl) { fontEl.innerHTML = ':root { --font-sans: \\'' + font + '\\', sans-serif; }'; }`,
-            `if (font !== 'Public Sans') {`,
-            `var lnk = document.createElement('link');`,
-            `lnk.rel = 'stylesheet';`,
-            `lnk.href = 'https://fonts.googleapis.com/css2?family=' + encodeURIComponent(font) + ':wght@400;500;600;700&display=swap';`,
-            `lnk.id = 'font-' + font.toLowerCase().replace(/\\s+/g, '-');`,
-            `document.head.appendChild(lnk);`,
-            `}}`
-          ].join(' ')
-        }, {
-          innerHTML: `
-            (function() {
-              var raw = localStorage.getItem('nuxt-ui-custom-colors');
-              if (raw) {
-                try {
-                  var colors = JSON.parse(raw);
-                  var vars = [];
-                  for (var name in colors) {
-                    for (var shade in colors[name]) {
-                      vars.push('--color-' + name + '-' + shade + ': ' + colors[name][shade] + ';');
-                    }
-                  }
-                  if (vars.length) {
-                    var el = document.getElementById('chat-custom-colors');
-                    if (el) { el.textContent = ':root { ' + vars.join(' ') + ' }'; }
-                  }
-                } catch(e) {}
+
+              var radius = num(T.radius, 0, 4);
+              if (radius !== undefined) { set('nuxt-ui-radius', ':root { --ui-radius: ' + radius + 'rem; }'); }
+
+              var fontSize = num(T.fontSize, 12, 20);
+              if (fontSize !== undefined && fontSize !== 16) { set('nuxt-ui-font-size', 'html { font-size: ' + fontSize + 'px; }'); }
+
+
+              set('nuxt-ui-black-as-primary', T.blackAsPrimary ? ':root { --ui-primary: black; } .dark { --ui-primary: white; }' : '');
+
+              var prefs = T.font || {};
+              var font = (prefs.sans && SAFE.test(prefs.sans)) ? prefs.sans : 'Public Sans';
+              var css = ':root { --font-sans: \\'' + font + '\\', sans-serif; }';
+              var serif = (prefs.serif && SAFE.test(prefs.serif)) ? prefs.serif : undefined;
+              var mono = (prefs.mono && SAFE.test(prefs.mono)) ? prefs.mono : undefined;
+              if (serif) { css += ' :root { --font-serif: \\'' + serif + '\\', serif; }'; }
+              if (mono) { css += ' :root { --font-mono: \\'' + mono + '\\', monospace; }'; }
+              var w = prefs.weights || {};
+              var wVars = Object.keys(w).map(function(step) { var n = num(w[step], 100, 900); return (SAFE.test(step) && n !== undefined) ? '--font-weight-' + step + ': ' + n + ';' : ''; }).filter(Boolean).join(' ');
+              if (wVars) { css += ' :root { ' + wVars + ' }'; }
+              var bodyRules = '';
+              var wn = num(w.normal, 100, 900);
+              if (wn !== undefined) { bodyRules += 'font-weight: ' + wn + '; '; }
+              if (prefs.uppercase) { bodyRules += 'text-transform: uppercase; '; }
+              if (prefs.italic) { bodyRules += 'font-style: italic; '; }
+              var ls = num(prefs.letterSpacing, -0.2, 1);
+              if (ls !== undefined && ls !== 0) { bodyRules += 'letter-spacing: ' + ls + 'em; '; }
+              var lh = num(prefs.lineHeight, 0.8, 3);
+              if (lh !== undefined) { bodyRules += 'line-height: ' + lh + '; '; }
+              if (bodyRules) { css += ' body { ' + bodyRules + '}'; }
+              if (Object.keys(prefs).length) { set('nuxt-ui-font', css); }
+              [font, serif, mono].forEach(function(name) {
+                if (!name || name === 'Public Sans') return;
+                var id = 'font-' + name.toLowerCase().replace(/\\s+/g, '-');
+                if (document.getElementById(id)) return;
+                var lnk = document.createElement('link');
+                lnk.rel = 'stylesheet';
+                lnk.href = 'https://fonts.googleapis.com/css2?family=' + encodeURIComponent(name) + ':wght@300;400;500;600;700;800&display=swap';
+                lnk.id = id;
+                document.head.appendChild(lnk);
+              });
+
+              var custom = T.customColors;
+              if (custom) {
+                var vars = [];
+                for (var name in custom) {
+                  for (var shade in custom[name]) { vars.push('--color-' + name + '-' + shade + ': ' + custom[name][shade] + ';'); }
+                }
+                if (vars.length) { set('nuxt-ui-custom-colors', ':root { ' + vars.join(' ') + ' }'); }
               }
-            })();
-          `.replace(/\s+/g, ' '),
-          type: 'text/javascript',
-          tagPriority: -1
-        }, {
-          innerHTML: `
-            (function() {
-              var raw = localStorage.getItem('nuxt-ui-css-variables');
-              if (raw) {
-                try {
-                  var cssVars = JSON.parse(raw);
-                  var defaults = ${JSON.stringify(cssVariableDefaults)};
-                  function merge(defs, overrides) {
-                    var result = [];
-                    for (var key in defs) { result.push(key + ': ' + (overrides[key] || defs[key]) + ';'); }
-                    for (var key in overrides) { if (!defs[key]) result.push(key + ': ' + overrides[key] + ';'); }
-                    return result;
-                  }
-                  var parts = [];
-                  if (cssVars.light && Object.keys(cssVars.light).length) {
-                    parts.push('.light { ' + merge(defaults.light, cssVars.light).join(' ') + ' }');
-                  }
-                  if (cssVars.dark && Object.keys(cssVars.dark).length) {
-                    parts.push('.dark { ' + merge(defaults.dark, cssVars.dark).join(' ') + ' }');
-                  }
-                  if (parts.length) {
-                    var el = document.getElementById('chat-css-variables');
-                    if (el) { el.textContent = parts.join(' '); }
-                  }
-                } catch(e) {}
+
+              var cssVars = T.cssVariables;
+              if (cssVars) {
+                var defaults = ${JSON.stringify(cssVariableDefaults)};
+                var merge = function(defs, overrides) {
+                  var result = [];
+                  for (var key in defs) { result.push(key + ': ' + (overrides[key] || defs[key]) + ';'); }
+                  for (var key2 in overrides) { if (!defs[key2]) result.push(key2 + ': ' + overrides[key2] + ';'); }
+                  return result;
+                };
+                var parts = [];
+                if (cssVars.light && Object.keys(cssVars.light).length) { parts.push('.light { ' + merge(defaults.light, cssVars.light).join(' ') + ' }'); }
+                if (cssVars.dark && Object.keys(cssVars.dark).length) { parts.push('.dark { ' + merge(defaults.dark, cssVars.dark).join(' ') + ' }'); }
+                if (parts.length) { set('nuxt-ui-css-variables', parts.join(' ')); }
               }
             })();
           `.replace(/\s+/g, ' '),
diff --git a/docs/app/utils/index.ts b/docs/app/utils/index.ts
index 177698b5c9..d07bd6fcad 100644
--- a/docs/app/utils/index.ts
+++ b/docs/app/utils/index.ts
@@ -3,3 +3,7 @@ import { splitByCase, upperFirst } from 'scule'
 export function upperName(name: string) {
   return splitByCase(name).map(p => upperFirst(p)).join('')
 }
+
+export function capitalize(value: string) {
+  return value.charAt(0).toUpperCase() + value.slice(1)
+}
diff --git a/docs/app/utils/theme.ts b/docs/app/utils/theme.ts
deleted file mode 100644
index 6e708a2a30..0000000000
--- a/docs/app/utils/theme.ts
+++ /dev/null
@@ -1,134 +0,0 @@
-import lucide from '../../../src/theme/icons'
-
-export const themeIcons = {
-  lucide,
-  phosphor: {
-    arrowDown: 'i-ph-arrow-down',
-    arrowLeft: 'i-ph-arrow-left',
-    arrowRight: 'i-ph-arrow-right',
-    arrowUp: 'i-ph-arrow-up',
-    caution: 'i-ph-warning-circle',
-    check: 'i-ph-check',
-    chevronDoubleLeft: 'i-ph-caret-double-left',
-    chevronDoubleRight: 'i-ph-caret-double-right',
-    chevronDown: 'i-ph-caret-down',
-    chevronLeft: 'i-ph-caret-left',
-    chevronRight: 'i-ph-caret-right',
-    chevronUp: 'i-ph-caret-up',
-    close: 'i-ph-x',
-    copy: 'i-ph-copy',
-    copyCheck: 'i-ph-check-circle',
-    dark: 'i-ph-moon',
-    drag: 'i-ph-dots-six-vertical',
-    ellipsis: 'i-ph-dots-three',
-    error: 'i-ph-x-circle',
-    external: 'i-ph-arrow-up-right',
-    eye: 'i-ph-eye',
-    eyeOff: 'i-ph-eye-slash',
-    file: 'i-ph-file',
-    folder: 'i-ph-folder',
-    folderOpen: 'i-ph-folder-open',
-    hash: 'i-ph-hash',
-    info: 'i-ph-info',
-    light: 'i-ph-sun',
-    loading: 'i-ph-circle-notch',
-    menu: 'i-ph-list',
-    minus: 'i-ph-minus',
-    panelClose: 'i-ph-caret-left',
-    panelOpen: 'i-ph-caret-right',
-    plus: 'i-ph-plus',
-    reload: 'i-ph-arrow-counter-clockwise',
-    search: 'i-ph-magnifying-glass',
-    stop: 'i-ph-square',
-    star: 'i-ph-star',
-    success: 'i-ph-check-circle',
-    system: 'i-ph-monitor',
-    tip: 'i-ph-lightbulb',
-    upload: 'i-ph-upload',
-    warning: 'i-ph-warning'
-  },
-  tabler: {
-    arrowDown: 'i-tabler-arrow-down',
-    arrowLeft: 'i-tabler-arrow-left',
-    arrowRight: 'i-tabler-arrow-right',
-    arrowUp: 'i-tabler-arrow-up',
-    caution: 'i-tabler-alert-square-rounded',
-    check: 'i-tabler-check',
-    chevronDoubleLeft: 'i-tabler-chevrons-left',
-    chevronDoubleRight: 'i-tabler-chevrons-right',
-    chevronDown: 'i-tabler-chevron-down',
-    chevronLeft: 'i-tabler-chevron-left',
-    chevronRight: 'i-tabler-chevron-right',
-    chevronUp: 'i-tabler-chevron-up',
-    close: 'i-tabler-x',
-    copy: 'i-tabler-copy',
-    copyCheck: 'i-tabler-copy-check',
-    dark: 'i-tabler-moon',
-    drag: 'i-tabler-grip-vertical',
-    ellipsis: 'i-tabler-dots',
-    error: 'i-tabler-square-rounded-x',
-    external: 'i-tabler-external-link',
-    eye: 'i-tabler-eye',
-    eyeOff: 'i-tabler-eye-off',
-    file: 'i-tabler-file',
-    folder: 'i-tabler-folder',
-    folderOpen: 'i-tabler-folder-open',
-    hash: 'i-tabler-hash',
-    info: 'i-tabler-info-square-rounded',
-    light: 'i-tabler-sun',
-    loading: 'i-tabler-loader-2',
-    menu: 'i-tabler-menu',
-    minus: 'i-tabler-minus',
-    panelClose: 'i-tabler-layout-sidebar-left-collapse',
-    panelOpen: 'i-tabler-layout-sidebar-left-expand',
-    plus: 'i-tabler-plus',
-    reload: 'i-tabler-reload',
-    search: 'i-tabler-search',
-    stop: 'i-tabler-player-stop',
-    star: 'i-tabler-star',
-    success: 'i-tabler-square-rounded-check',
-    system: 'i-tabler-device-desktop',
-    tip: 'i-tabler-bulb',
-    upload: 'i-tabler-upload',
-    warning: 'i-tabler-alert-triangle'
-  }
-}
-
-export type ThemeIcons = keyof typeof themeIcons
-
-export const cssVariableDefaults = {
-  light: {
-    '--ui-text-dimmed': 'var(--ui-color-neutral-400)',
-    '--ui-text-muted': 'var(--ui-color-neutral-500)',
-    '--ui-text-toned': 'var(--ui-color-neutral-600)',
-    '--ui-text': 'var(--ui-color-neutral-700)',
-    '--ui-text-highlighted': 'var(--ui-color-neutral-900)',
-    '--ui-text-inverted': 'white',
-    '--ui-bg': 'white',
-    '--ui-bg-muted': 'var(--ui-color-neutral-50)',
-    '--ui-bg-elevated': 'var(--ui-color-neutral-100)',
-    '--ui-bg-accented': 'var(--ui-color-neutral-200)',
-    '--ui-bg-inverted': 'var(--ui-color-neutral-900)',
-    '--ui-border': 'var(--ui-color-neutral-200)',
-    '--ui-border-muted': 'var(--ui-color-neutral-200)',
-    '--ui-border-accented': 'var(--ui-color-neutral-300)',
-    '--ui-border-inverted': 'var(--ui-color-neutral-900)'
-  },
-  dark: {
-    '--ui-text-dimmed': 'var(--ui-color-neutral-500)',
-    '--ui-text-muted': 'var(--ui-color-neutral-400)',
-    '--ui-text-toned': 'var(--ui-color-neutral-300)',
-    '--ui-text': 'var(--ui-color-neutral-200)',
-    '--ui-text-highlighted': 'white',
-    '--ui-text-inverted': 'var(--ui-color-neutral-900)',
-    '--ui-bg': 'var(--ui-color-neutral-900)',
-    '--ui-bg-muted': 'var(--ui-color-neutral-800)',
-    '--ui-bg-elevated': 'var(--ui-color-neutral-800)',
-    '--ui-bg-accented': 'var(--ui-color-neutral-700)',
-    '--ui-bg-inverted': 'white',
-    '--ui-border': 'var(--ui-color-neutral-800)',
-    '--ui-border-muted': 'var(--ui-color-neutral-700)',
-    '--ui-border-accented': 'var(--ui-color-neutral-700)',
-    '--ui-border-inverted': 'white'
-  }
-} as const
diff --git a/docs/app/utils/theme/engine/index.ts b/docs/app/utils/theme/engine/index.ts
new file mode 100644
index 0000000000..86b43bcf4c
--- /dev/null
+++ b/docs/app/utils/theme/engine/index.ts
@@ -0,0 +1,5 @@
+export * from './types'
+export * from './serialize'
+export * from './presets'
+export * from './palette'
+export * from './sections'
diff --git a/docs/app/utils/theme/engine/palette.ts b/docs/app/utils/theme/engine/palette.ts
new file mode 100644
index 0000000000..89b567df3a
--- /dev/null
+++ b/docs/app/utils/theme/engine/palette.ts
@@ -0,0 +1,643 @@
+/**
+ * Colour maths for the studio's palettes: sRGB ↔ OKLCH conversion, then the
+ * cubic-bezier ramp model built on top of it.
+ *
+ * The conversion half (Björn Ottosson's OKLab) is dependency-free so the
+ * engine stays portable: parse any CSS colour the studio meets, move through
+ * OKLCH, come back out as a gamut-safe `oklch(…)` string. The ramp half
+ * samples one bezier per channel across the shade stops, and can also run
+ * backwards, fitting curves to a pasted palette.
+ */
+import type { Shade, ShadeStep } from './types'
+import { SHADES, SHADE_SETS, SHADE_STEPS } from './types'
+
+/* ------------------------------------------------------- sRGB ↔ OKLCH -- */
+
+export interface Oklch {
+  /** Perceptual lightness, 0–1 */
+  l: number
+  /** Chroma, 0–~0.4 in sRGB */
+  c: number
+  /** Hue in degrees, 0–360 */
+  h: number
+}
+
+function srgbToLinear(c: number): number {
+  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4)
+}
+
+function linearToSrgb(c: number): number {
+  return c <= 0.0031308 ? c * 12.92 : 1.055 * Math.pow(c, 1 / 2.4) - 0.055
+}
+
+export function hexToRgb(hex: string): [number, number, number] {
+  let value = hex.replace('#', '')
+  if (value.length === 3) {
+    value = value.split('').map(ch => ch + ch).join('')
+  }
+  return [
+    Number.parseInt(value.slice(0, 2), 16) / 255,
+    Number.parseInt(value.slice(2, 4), 16) / 255,
+    Number.parseInt(value.slice(4, 6), 16) / 255
+  ]
+}
+
+export function rgbToHex([r, g, b]: [number, number, number]): string {
+  const to = (c: number) => Math.round(Math.min(1, Math.max(0, c)) * 255).toString(16).padStart(2, '0')
+  return `#${to(r)}${to(g)}${to(b)}`.toUpperCase()
+}
+
+export function rgbToOklch([r, g, b]: [number, number, number]): Oklch {
+  const lr = srgbToLinear(r)
+  const lg = srgbToLinear(g)
+  const lb = srgbToLinear(b)
+
+  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb)
+  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb)
+  const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb)
+
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s
+  const a = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s
+  const bb = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s
+
+  const c = Math.sqrt(a * a + bb * bb)
+  let h = Math.atan2(bb, a) * 180 / Math.PI
+  if (h < 0) h += 360
+
+  return { l: L, c, h }
+}
+
+/** Raw conversion, channels may fall outside [0, 1] when out of gamut. */
+function oklchToLinearRgb({ l: L, c, h }: Oklch): [number, number, number] {
+  const hr = h * Math.PI / 180
+  const a = Math.cos(hr) * c
+  const b = Math.sin(hr) * c
+
+  const l = Math.pow(L + 0.3963377774 * a + 0.2158037573 * b, 3)
+  const m = Math.pow(L - 0.1055613458 * a - 0.0638541728 * b, 3)
+  const s = Math.pow(L - 0.0894841775 * a - 1.291485548 * b, 3)
+
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s
+  ]
+}
+
+/** Gamut-clipped sRGB channels (0–1), for showing hex/rgb equivalents. */
+export function oklchToRgb(color: Oklch): [number, number, number] {
+  return oklchToLinearRgb(color).map(channel =>
+    Math.min(1, Math.max(0, linearToSrgb(channel)))) as [number, number, number]
+}
+
+const GAMUT_EPSILON = 0.000005
+
+export function inGamut(color: Oklch): boolean {
+  return oklchToLinearRgb(color).every(channel => channel >= -GAMUT_EPSILON && channel <= 1 + GAMUT_EPSILON)
+}
+
+/** Reduce chroma (binary search) until the color fits in sRGB. */
+export function clampToGamut(color: Oklch): Oklch {
+  if (inGamut(color)) return color
+
+  let low = 0
+  let high = color.c
+  for (let i = 0; i < 24; i++) {
+    const mid = (low + high) / 2
+    if (inGamut({ ...color, c: mid })) {
+      low = mid
+    } else {
+      high = mid
+    }
+  }
+  return { ...color, c: low }
+}
+
+export function oklchToHex(color: Oklch): string {
+  const clamped = clampToGamut(color)
+  return rgbToHex(oklchToLinearRgb(clamped).map(linearToSrgb) as [number, number, number])
+}
+
+export function hexToOklch(hex: string): Oklch {
+  return rgbToOklch(hexToRgb(hex))
+}
+
+/**
+ * Serialize to tailwind v4's `oklch(62.3% 0.214 259.815)` shape. No gamut
+ * clamp, so wider-than-sRGB values (tailwind's own ramps have them) survive
+ * a round-trip. Achromatic hue is atan2 noise, zero it.
+ */
+export function formatOklch(color: Oklch): string {
+  const c = +color.c.toFixed(3)
+  return `oklch(${+(color.l * 100).toFixed(1)}% ${c} ${c === 0 ? 0 : +color.h.toFixed(3)})`
+}
+
+/** Parse a CSS color into OKLCH, the forms the studio meets: hex, `oklch(…)`, `rgb(…)`. */
+export function parseColor(value: string): Oklch | undefined {
+  // Ramp lookups can pass undefined, unparseable, not a .trim() throw.
+  if (typeof value !== 'string') return undefined
+  const input = value.trim()
+
+  // the two keywords the theme system actually uses (library token defaults)
+  if (input === 'white') return { l: 1, c: 0, h: 0 }
+  if (input === 'black') return { l: 0, c: 0, h: 0 }
+
+  // Only 3/6-digit hex, truncated/alpha hex would feed NaN into the fitter.
+  if (/^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(input)) {
+    return rgbToOklch(hexToRgb(input))
+  }
+
+  // `none` is CSS Color 4's missing-component keyword, tailwind ≥4.3.3
+  // emits it for achromatic hues (`oklch(98.5% 0 none)`); it reads as 0 here.
+  const oklch = input.match(/^oklch\(\s*([\d.]+)(%?)\s+([\d.]+|none)\s+([\d.]+|none)/i)
+  if (oklch) {
+    const channel = (value: string) => value.toLowerCase() === 'none' ? 0 : Number(value)
+    return { l: Number(oklch[1]) / (oklch[2] === '%' ? 100 : 1), c: channel(oklch[3]!), h: channel(oklch[4]!) }
+  }
+
+  const rgb = input.match(/^rgba?\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)/i)
+  if (rgb) {
+    return rgbToOklch([Number(rgb[1]) / 255, Number(rgb[2]) / 255, Number(rgb[3]) / 255])
+  }
+
+  return undefined
+}
+
+/** Normalize a CSS color value to a canonical `oklch(…)` string. */
+export function parseCssColor(value: string): string | undefined {
+  const color = parseColor(value)
+  return color ? formatOklch(color) : undefined
+}
+
+/**
+ * Composite `color` at `alpha` over `backdrop`, what the browser paints for
+ * `bg-primary/10`. Blends in gamma-encoded sRGB (not linear) to match the
+ * rendered pixel. Undefined when either input is unparseable.
+ */
+export function blendColors(color: string, backdrop: string, alpha: number): string | undefined {
+  const fg = parseColor(color)
+  const bg = parseColor(backdrop)
+  if (!fg || !bg) return undefined
+
+  const top = oklchToRgb(clampToGamut(fg))
+  const under = oklchToRgb(clampToGamut(bg))
+  return rgbToHex(top.map((channel, i) => channel * alpha + under[i]! * (1 - alpha)) as [number, number, number])
+}
+
+/** WCAG 2.x relative luminance, linear RGB is exactly what the formula wants. */
+function luminance(color: Oklch): number {
+  const [r, g, b] = oklchToLinearRgb(clampToGamut(color)).map(channel => Math.min(1, Math.max(0, channel))) as [number, number, number]
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+
+/**
+ * WCAG 2.x contrast ratio between two CSS colors, 1–21. `null` when either
+ * input is unparseable, unknown, not a fabricated ratio.
+ */
+export function contrastRatio(colorA: string, colorB: string): number | null {
+  const a = parseColor(colorA)
+  const b = parseColor(colorB)
+  if (!a || !b) return null
+  const la = luminance(a)
+  const lb = luminance(b)
+  const [lighter, darker] = la > lb ? [la, lb] : [lb, la]
+  return (lighter + 0.05) / (darker + 0.05)
+}
+
+/* -------------------------------------------------------------- ramps -- */
+
+/**
+ * One channel of a palette (L, C or H) as a devtools-style cubic bezier
+ * sampled across the shade stops (x: 0 = shade 50 … 1 = shade 950).
+ * y values are in channel units; handles may overshoot the endpoints.
+ */
+export interface ChannelCurve {
+  /** Channel value at shade 50 */
+  y0: number
+  /** Channel value at shade 950 */
+  y1: number
+  p1x: number
+  p1y: number
+  p2x: number
+  p2y: number
+}
+
+export interface PaletteCurveParams {
+  lightness: ChannelCurve
+  chroma: ChannelCurve
+  hue: ChannelCurve
+}
+
+/** Fitted to tailwind v4's ramps, only seeds empty states; real params come from fitPalette(). */
+export const CURVE_DEFAULTS: PaletteCurveParams = {
+  lightness: { y0: 0.977, y1: 0.27, p1x: 0.1, p1y: 1.012, p2x: 0.925, p2y: 0.376 },
+  chroma: { y0: 0.016, y1: 0.08, p1x: 0.4, p1y: 0.3, p2x: 0.6, p2y: 0.25 },
+  hue: { y0: 250, y1: 250, p1x: 0.33, p1y: 250, p2x: 0.66, p2y: 250 }
+}
+
+/** Neutrals run to L 0.13 like tailwind's grays, so dark-mode backgrounds stay genuinely dark. */
+export const NEUTRAL_CURVE_DEFAULTS: PaletteCurveParams = {
+  lightness: { ...CURVE_DEFAULTS.lightness, y1: 0.13 },
+  chroma: { y0: 0.005, y1: 0.01, p1x: 0.4, p1y: 0.01, p2x: 0.6, p2y: 0.01 },
+  hue: CURVE_DEFAULTS.hue
+}
+
+/**
+ * The editor's modifier lens over base curves, scaled by an overall amount.
+ * Pure: always derived fresh from the base, never compounding.
+ */
+export interface PaletteEffects {
+  lightness: number
+  contrast: number
+  saturation: number
+  hueShift: number
+}
+
+export const PALETTE_EFFECT_DEFAULTS: PaletteEffects = { lightness: 0, contrast: 0, saturation: 0, hueShift: 0 }
+
+/**
+ * A stop locked to an exact OKLCH, "pin this brand colour, edit around it".
+ * Stored absolute so it survives curve drags and modifiers (see pinField).
+ */
+export interface PalettePin {
+  shade: Shade
+  l: number
+  c: number
+  h: number
+}
+
+/** A persisted palette. `fineStops` predates the density model, read, never written. */
+export type StoredPaletteParams = PaletteCurveParams & { effects?: PaletteEffects, amount?: number, stopStep?: ShadeStep, fineStops?: boolean, pins?: PalettePin[] }
+
+/** The density a persisted palette generates at. */
+export function storedStopStep(stored?: { stopStep?: ShadeStep, fineStops?: boolean }): ShadeStep {
+  return stored?.stopStep ?? (stored?.fineStops ? 50 : 100)
+}
+
+/**
+ * Density read back from a ramp's stops: the coarsest set covering all of
+ * them; a hand-edited mix no density emits falls to the finest.
+ */
+export function detectStopStep(shades: Partial<Record<Shade, string>>): ShadeStep {
+  const present = Object.keys(shades).map(Number) as Shade[]
+  return SHADE_STEPS.find(step => present.every(shade => SHADE_SETS[step].includes(shade))) ?? 10
+}
+
+/** The stop closest to a value, where an orphaned shade reference lands. */
+export function nearestShade(value: number, stops: readonly Shade[]): Shade {
+  return stops.reduce((best, stop) => Math.abs(stop - value) < Math.abs(best - value) ? stop : best)
+}
+
+// Pin influence width (ramp x). Wider than the closest pin spacing the solve
+// goes ill-conditioned (clustered pins blow neighbours to white), so sigma
+// narrows to that spacing, floored.
+const PIN_KERNEL_SIGMA_MAX = 0.2
+const PIN_KERNEL_SIGMA_MIN = 0.04
+
+function pinKernel(distance: number, sigma: number): number {
+  const t = distance / sigma
+  return Math.exp(-t * t)
+}
+
+/**
+ * Gauss–Jordan with partial pivoting (≤19 pins, trivially fast). A
+ * near-singular pivot collapses that weight to 0 rather than exploding.
+ */
+function solveLinear(a: number[][], b: number[]): number[] {
+  const n = b.length
+  const m = a.map((row, i) => [...row, b[i]!])
+  for (let col = 0; col < n; col++) {
+    let pivot = col
+    for (let row = col + 1; row < n; row++) {
+      if (Math.abs(m[row]![col]!) > Math.abs(m[pivot]![col]!)) pivot = row
+    }
+    ;[m[col], m[pivot]] = [m[pivot]!, m[col]!]
+    const diag = m[col]![col]!
+    if (Math.abs(diag) < 1e-12) continue
+    for (let row = 0; row < n; row++) {
+      if (row === col) continue
+      const factor = m[row]![col]! / diag
+      for (let k = col; k <= n; k++) m[row]![k]! -= factor * m[col]![k]!
+    }
+  }
+  return m.map((row, i) => (Math.abs(row[i]!) < 1e-12 ? 0 : row[n]! / row[i]!))
+}
+
+/**
+ * Additive correction field locking the pins: radial-basis interpolation of
+ * the pin deltas, exact at a pinned x, decaying smoothly elsewhere.
+ */
+function pinField(pins: PalettePin[], base: (x: number) => { l: number, c: number, h: number }) {
+  const xs = pins.map(pin => shadeX(pin.shade))
+
+  // Kernel width: the closest pin pair, clamped. Infinity (a single pin) → MAX.
+  let minSpacing = Infinity
+  for (let i = 0; i < xs.length; i++) {
+    for (let j = i + 1; j < xs.length; j++) {
+      minSpacing = Math.min(minSpacing, Math.abs(xs[i]! - xs[j]!))
+    }
+  }
+  const sigma = Math.min(PIN_KERNEL_SIGMA_MAX, Math.max(PIN_KERNEL_SIGMA_MIN, minSpacing))
+
+  const matrix = xs.map(xi => xs.map(xj => pinKernel(Math.abs(xi - xj), sigma)))
+
+  // Hue is cyclic: chain-unwrap targets in x order (each within ±180° of the
+  // previous, anchored to the base) so runs of pins take the short arc.
+  const order = xs.map((_, i) => i).sort((i, j) => xs[i]! - xs[j]!)
+  const hueTarget: number[] = Array.from({ length: pins.length })
+  let prevHue = base(xs[order[0]!]!).h
+  for (const i of order) {
+    let h = pins[i]!.h
+    while (h - prevHue > 180) h -= 360
+    while (h - prevHue < -180) h += 360
+    hueTarget[i] = h
+    prevHue = h
+  }
+
+  const deltaL: number[] = []
+  const deltaC: number[] = []
+  const deltaH: number[] = []
+  pins.forEach((pin, i) => {
+    const b = base(xs[i]!)
+    deltaL.push(pin.l - b.l)
+    deltaC.push(pin.c - b.c)
+    deltaH.push(hueTarget[i]! - b.h)
+  })
+  const wl = solveLinear(matrix, deltaL)
+  const wc = solveLinear(matrix, deltaC)
+  const wh = solveLinear(matrix, deltaH)
+  return (x: number) => {
+    let dl = 0
+    let dc = 0
+    let dh = 0
+    for (let j = 0; j < xs.length; j++) {
+      const k = pinKernel(Math.abs(x - xs[j]!), sigma)
+      dl += wl[j]! * k
+      dc += wc[j]! * k
+      dh += wh[j]! * k
+    }
+    return { dl, dc, dh }
+  }
+}
+
+export function isDefaultEffects(effects?: PaletteEffects, amount = 100): boolean {
+  if (amount !== 100) return false
+  if (!effects) return true
+  return (Object.keys(PALETTE_EFFECT_DEFAULTS) as Array<keyof PaletteEffects>)
+    .every(key => effects[key] === PALETTE_EFFECT_DEFAULTS[key])
+}
+
+export function applyPaletteEffects(base: PaletteCurveParams, effects?: PaletteEffects, amount = 100): PaletteCurveParams {
+  const target = structuredClone(base)
+  if (isDefaultEffects(effects, amount)) return target
+
+  // 100% applies as set; lower blends toward the base, higher extrapolates.
+  const strength = amount / 100
+  const effective = (key: keyof PaletteEffects) =>
+    PALETTE_EFFECT_DEFAULTS[key] + ((effects?.[key] ?? PALETTE_EFFECT_DEFAULTS[key]) - PALETTE_EFFECT_DEFAULTS[key]) * strength
+
+  // Contrast expands about the curve's own midpoint, then the shift slides
+  // the whole ramp; every point clamps to the physical [0, 1] window.
+  const lightness = target.lightness
+  const mid = (lightness.y0 + lightness.y1) / 2
+  const span = 1 + effective('contrast') / 100
+  const shift = effective('lightness') / 100
+  const mapLightness = (value: number) => Math.min(1, Math.max(0, mid + (value - mid) * span + shift))
+  lightness.y0 = mapLightness(lightness.y0)
+  lightness.y1 = mapLightness(lightness.y1)
+  lightness.p1y = mapLightness(lightness.p1y)
+  lightness.p2y = mapLightness(lightness.p2y)
+
+  // Multiplicative, plus a small additive floor when boosting so near-gray
+  // ramps (where a multiply is a no-op) respond too.
+  const saturation = effective('saturation') / 100
+  const factor = 1 + saturation
+  const floor = Math.max(0, saturation) * 0.02
+  const mapChroma = (value: number) => Math.min(0.4, Math.max(0, value * factor + floor))
+  const chroma = target.chroma
+  chroma.y0 = mapChroma(chroma.y0)
+  chroma.y1 = mapChroma(chroma.y1)
+  chroma.p1y = mapChroma(chroma.p1y)
+  chroma.p2y = mapChroma(chroma.p2y)
+
+  // A uniform shift keeps the curve continuous; re-center by full turns so
+  // the mean stays in [0, 360).
+  const hueShift = effective('hueShift')
+  const hue = target.hue
+  hue.y0 += hueShift
+  hue.y1 += hueShift
+  hue.p1y += hueShift
+  hue.p2y += hueShift
+  const mean = (hue.y0 + hue.y1 + hue.p1y + hue.p2y) / 4
+  const turns = -360 * Math.floor(mean / 360)
+  if (turns !== 0) {
+    hue.y0 += turns
+    hue.y1 += turns
+    hue.p1y += turns
+    hue.p2y += turns
+  }
+
+  return target
+}
+
+function cubicBezier(t: number, a: number, b: number, c: number, d: number): number {
+  const u = 1 - t
+  return u * u * u * a + 3 * u * u * t * b + 3 * u * t * t * c + t * t * t * d
+}
+
+/**
+ * Sample a channel curve at ramp position `x` (0–1). Control x clamps into
+ * [0, 1], keeping x(t) monotonic so the bisection is well-defined.
+ */
+export function sampleCurve(x: number, curve: ChannelCurve): number {
+  const p1x = Math.min(1, Math.max(0, curve.p1x))
+  const p2x = Math.min(1, Math.max(0, curve.p2x))
+
+  let lo = 0
+  let hi = 1
+  for (let i = 0; i < 32; i++) {
+    const mid = (lo + hi) / 2
+    if (cubicBezier(mid, 0, p1x, p2x, 1) < x) {
+      lo = mid
+    } else {
+      hi = mid
+    }
+  }
+  const t = (lo + hi) / 2
+
+  return cubicBezier(t, curve.y0, curve.p1y, curve.p2y, curve.y1)
+}
+
+/**
+ * A shade's position along the curve, keyed by VALUE not array index, so
+ * stops keep their exact colour across densities and midpoints land between
+ * their neighbours.
+ */
+export function shadeX(shade: Shade): number {
+  if (shade === 50) return 0
+  if (shade === 950) return 1
+  return shade / 1000
+}
+
+/**
+ * Sampler for the pin-corrected ramp: raw channel values at any x, hue
+ * unwrapped, no gamut clamp, so a curve drawn through them stays continuous.
+ */
+export function buildRampSampler(params: PaletteCurveParams, pins: PalettePin[] = []): (x: number) => { l: number, c: number, h: number } {
+  const base = (x: number) => ({
+    l: sampleCurve(x, params.lightness),
+    c: sampleCurve(x, params.chroma),
+    h: sampleCurve(x, params.hue)
+  })
+  const correct = pins.length ? pinField(pins, base) : undefined
+  return (x: number) => {
+    const b = base(x)
+    if (!correct) return b
+    const d = correct(x)
+    return { l: b.l + d.dl, c: b.c + d.dc, h: b.h + d.dh }
+  }
+}
+
+export function generatePalette(params: PaletteCurveParams, step: ShadeStep = 100, pins: PalettePin[] = []): Record<Shade, string> {
+  const result = {} as Record<Shade, string>
+
+  const base = (x: number) => ({
+    l: sampleCurve(x, params.lightness),
+    c: sampleCurve(x, params.chroma),
+    h: sampleCurve(x, params.hue)
+  })
+  // Correction applies pre-clamp, so an in-gamut pin target is hit exactly.
+  const correct = pins.length ? pinField(pins, base) : undefined
+
+  for (const shade of SHADE_SETS[step]) {
+    const x = shadeX(shade)
+    const b = base(x)
+    const d = correct ? correct(x) : { dl: 0, dc: 0, dh: 0 }
+
+    // Clamp here, not in the serializer: clampToGamut only searches chroma,
+    // so an overshooting curve would emit oklch(112% …) verbatim; and a
+    // negative or 4-digit hue fails the sanitizer's canonical-oklch check
+    // and silently DROPS the shade.
+    result[shade] = formatOklch(clampToGamut({
+      l: Math.min(1, Math.max(0, b.l + d.dl)),
+      c: Math.max(0, b.c + d.dc),
+      h: ((((b.h + d.dh) % 360) + 360) % 360)
+    }))
+  }
+
+  return result
+}
+
+/**
+ * Fit a channel curve to sampled points (x ascending, 0 and 1 included):
+ * endpoints pinned, handles by coordinate descent, deterministic and fast
+ * enough per palette selection.
+ */
+export function fitCurve(points: Array<[number, number]>): ChannelCurve {
+  // Nothing to fit, a flat zero curve beats a TypeError.
+  if (!points.length) {
+    return { y0: 0, p1x: 0.33, p1y: 0, p2x: 0.66, p2y: 0, y1: 0 }
+  }
+  const y0 = points[0]![1]
+  const y1 = points[points.length - 1]![1]
+  const span = Math.max(Math.abs(y1 - y0), 1e-6)
+
+  const lerp = (x: number) => y0 + (y1 - y0) * x
+
+  const error = (curve: ChannelCurve) => {
+    let sum = 0
+    for (const [x, y] of points) {
+      const d = sampleCurve(x, curve) - y
+      sum += d * d
+    }
+    return sum
+  }
+
+  const keys = ['p1x', 'p1y', 'p2x', 'p2y'] as const
+
+  // Several starting handle placements so a bad basin doesn't trap the fit.
+  let winner: ChannelCurve | undefined
+  let winnerError = Infinity
+
+  for (const [p1x, p2x] of [[0.33, 0.66], [0.15, 0.85], [0.45, 0.55]] as const) {
+    const curve: ChannelCurve = { y0, y1, p1x, p1y: lerp(p1x), p2x, p2y: lerp(p2x) }
+    let best = error(curve)
+    let stepX = 0.2
+    let stepY = span * 0.4
+
+    for (let round = 0; round < 200; round++) {
+      let improved = false
+      for (const key of keys) {
+        const isX = key === 'p1x' || key === 'p2x'
+        const step = isX ? stepX : stepY
+        for (const direction of [1, -1]) {
+          for (;;) {
+            const previous = curve[key]
+            const next = previous + direction * step
+            curve[key] = isX ? Math.min(1, Math.max(0, next)) : next
+            const err = error(curve)
+            if (err < best - 1e-14) {
+              best = err
+              improved = true
+            } else {
+              curve[key] = previous
+              break
+            }
+          }
+        }
+      }
+      if (!improved) {
+        stepX /= 2
+        stepY /= 2
+        if (stepX < 1e-4) break
+      }
+    }
+
+    if (best < winnerError) {
+      winnerError = best
+      winner = curve
+    }
+  }
+
+  return winner!
+}
+
+/**
+ * Work backwards from an existing palette (e.g. a tailwind ramp) to curve
+ * params that reproduce it, so editing always starts from the real thing.
+ */
+export function fitPalette(shades: Partial<Record<Shade, string>>): PaletteCurveParams {
+  const stops: Array<{ x: number, color: Oklch }> = []
+  for (const [index, shade] of SHADES.entries()) {
+    // Accept hex or oklch, older saved docs and pasted ramps are hex.
+    const color = shades[shade] ? parseColor(shades[shade]!) : undefined
+    if (color) {
+      stops.push({ x: index / (SHADES.length - 1), color })
+    }
+  }
+
+  // Nothing parseable, stock curves beat letting fitCurve([]) throw.
+  if (!stops.length) {
+    return structuredClone(CURVE_DEFAULTS)
+  }
+
+  // Hue is noise below ~0.01 chroma, borrow the nearest chromatic stop.
+  const chromatic = stops.filter(stop => stop.color.c >= 0.01)
+  const hues = stops.map((stop) => {
+    if (stop.color.c >= 0.01 || !chromatic.length) return stop.color.h
+    const nearest = chromatic.reduce((a, b) => Math.abs(a.x - stop.x) < Math.abs(b.x - stop.x) ? a : b)
+    return nearest.color.h
+  })
+
+  // Unwrap so the sequence is continuous even across the 0/360 seam.
+  for (let i = 1; i < hues.length; i++) {
+    while (hues[i]! - hues[i - 1]! > 180) hues[i]! -= 360
+    while (hues[i]! - hues[i - 1]! < -180) hues[i]! += 360
+  }
+
+  return {
+    lightness: fitCurve(stops.map(stop => [stop.x, stop.color.l])),
+    chroma: fitCurve(stops.map(stop => [stop.x, stop.color.c])),
+    hue: fitCurve(stops.map((stop, i) => [stop.x, hues[i]!]))
+  }
+}
diff --git a/docs/app/utils/theme/engine/presets.ts b/docs/app/utils/theme/engine/presets.ts
new file mode 100644
index 0000000000..a4181be0e9
--- /dev/null
+++ b/docs/app/utils/theme/engine/presets.ts
@@ -0,0 +1,545 @@
+import type { ThemeDoc } from './types'
+
+export interface ThemePreset {
+  id: string
+  name: string
+  description: string
+  icon: string
+  doc: ThemeDoc
+}
+
+/** The stock preset, what an untouched theme already is. */
+export const DEFAULT_PRESET_ID = 'nuxt-ui'
+
+/**
+ * Presets are plain ThemeDocs: applying one replaces the current document.
+ * Each deliberately exercises a different engine capability, so they double
+ * as living tests of the schema.
+ */
+export const presets: ThemePreset[] = [{
+  id: 'nuxt-ui',
+  name: 'Default',
+  description: 'The stock theme, everything inherited.',
+  icon: 'i-simple-icons-nuxt',
+  doc: {
+    version: 1
+  }
+}, {
+  id: 'mono',
+  name: 'Mono',
+  description: 'Black on a pure gray neutral, generous radius, quiet surfaces.',
+  icon: 'i-lucide-contrast',
+  doc: {
+    version: 1,
+    blackAsPrimary: true,
+    colors: {
+      neutral: 'neutral'
+    },
+    radius: 0.5,
+    font: { sans: 'Geist' },
+    style: {
+      defaults: {
+        variants: {
+          inputs: 'subtle'
+        }
+      },
+      tokenShades: {
+        '--ui-bg': { dark: 950 },
+        '--ui-bg-muted': { light: 100, dark: 900 },
+        '--ui-bg-elevated': { light: 100, dark: 900 },
+        '--ui-bg-accented': { light: 200, dark: 800 },
+        '--ui-text': { light: 900, dark: 100 },
+        '--ui-text-highlighted': { light: 950, dark: 50 }
+      }
+    }
+  }
+}, {
+  id: 'carbon',
+  name: 'Carbon',
+  description: 'Amber on a warm carbon neutral, with ink-dark borders throughout.',
+  icon: 'i-lucide-zap',
+  doc: {
+    version: 1,
+    // Sculpted warm neutral: lilac-tinted paper into pure carbon.
+    palettes: {
+      carbon: {
+        shades: {
+          50: 'oklch(98.5% 0.017 447.457)',
+          100: 'oklch(95.9% 0.036 438.639)',
+          200: 'oklch(92.6% 0.054 428.8)',
+          300: 'oklch(87% 0.053 417.734)',
+          400: 'oklch(70.5% 0.032 405.184)',
+          500: 'oklch(55.3% 0.014 390.836)',
+          600: 'oklch(44.7% 0.001 374.343)',
+          700: 'oklch(35.9% 0 0)',
+          800: 'oklch(28% 0 0)',
+          900: 'oklch(20.8% 0 0)',
+          950: 'oklch(14.1% 0.005 285.805)'
+        }
+      }
+    },
+    colors: {
+      primary: 'amber',
+      secondary: 'yellow',
+      neutral: 'carbon'
+    },
+    radius: 0.5,
+    font: { sans: 'Outfit' },
+    icons: 'tabler',
+    style: {
+      defaults: { variants: { buttons: 'solid', panels: 'subtle', inputs: 'subtle' } },
+      tokenShades: {
+        '--ui-bg': { light: 50, dark: 800 },
+        '--ui-bg-muted': { light: 300, dark: 700 },
+        '--ui-bg-elevated': { light: 300, dark: 700 },
+        '--ui-bg-accented': { light: 400, dark: 600 },
+        '--ui-bg-inverted': { light: 900, dark: 50 },
+        '--ui-text-inverted': { light: 50 },
+        '--ui-text-dimmed': { light: 500, dark: 400 },
+        '--ui-text-muted': { light: 800, dark: 300 },
+        '--ui-text-toned': { light: 900 },
+        '--ui-text': { light: 900 },
+        '--ui-text-highlighted': { light: 950, dark: 100 },
+        // Light keeps the ink hairline; dark has to run the other way, a
+        // border below the surface's own lightness just reads as a seam.
+        '--ui-border': { light: 950, dark: 600 },
+        // dark is left at the library's own neutral-700, restating it would
+        // only add a line the importer then has to recognise as generated
+        '--ui-border-muted': { light: 400 },
+        '--ui-border-accented': { light: 950, dark: 500 },
+        '--ui-border-inverted': { light: 500, dark: 50 }
+      }
+    }
+  }
+}, {
+  id: 'orchard',
+  name: 'Orchard',
+  description: 'Orange on deep sage greens, subtle surfaces, foliage-tinted throughout.',
+  icon: 'i-lucide-citrus',
+  doc: {
+    version: 1,
+    // Green-tinted neutral whose light end starts far below white, the
+    // whole page sits on foliage.
+    palettes: {
+      grove: {
+        shades: {
+          50: 'oklch(91% 0.036 140.516)',
+          100: 'oklch(84.9% 0.042 140.374)',
+          200: 'oklch(78.6% 0.048 140.574)',
+          300: 'oklch(72.3% 0.053 141.491)',
+          400: 'oklch(65.8% 0.057 142.244)',
+          500: 'oklch(59.1% 0.051 142.85)',
+          600: 'oklch(52.2% 0.042 143.373)',
+          700: 'oklch(45.2% 0.034 143.84)',
+          800: 'oklch(38.1% 0.028 144.268)',
+          900: 'oklch(31.1% 0.022 144.667)',
+          950: 'oklch(24.2% 0.017 145.041)'
+        }
+      }
+    },
+    colors: {
+      primary: 'orange',
+      neutral: 'grove'
+    },
+    font: { sans: 'DM Sans' },
+    icons: 'remix',
+    tokens: {
+      light: {
+        '--ui-bg': 'var(--ui-color-neutral-50)',
+        '--ui-text-inverted': 'var(--ui-color-neutral-50)'
+      },
+      dark: {
+        '--ui-text-highlighted': 'var(--ui-color-neutral-50)'
+      }
+    },
+    style: {
+      defaults: { variant: 'subtle' },
+      tokenShades: {
+        '--ui-bg-muted': { light: 100 },
+        '--ui-bg-elevated': { light: 200 },
+        '--ui-bg-accented': { light: 300 },
+        '--ui-success': { light: 600, dark: 300 },
+        '--ui-error': { light: 600, dark: 300 }
+      }
+    }
+  }
+}, {
+  id: 'marshmallow',
+  name: 'Marshmallow',
+  description: 'Pastel pink softness with mauve-tinted grays.',
+  icon: 'i-lucide-candy',
+  doc: {
+    version: 1,
+    // Sculpted pink-mauve neutral, chroma peaks mid-ramp.
+    palettes: {
+      'saturated-mauve': {
+        shades: {
+          50: 'oklch(96.1% 0.021 325.68)',
+          100: 'oklch(92.4% 0.039 325.829)',
+          200: 'oklch(88% 0.057 325.83)',
+          300: 'oklch(81.2% 0.073 325.398)',
+          400: 'oklch(66.1% 0.084 323.292)',
+          500: 'oklch(52.4% 0.079 322.443)',
+          600: 'oklch(42.7% 0.064 322.128)',
+          700: 'oklch(34.6% 0.048 322.004)',
+          800: 'oklch(27.4% 0.034 321.983)',
+          900: 'oklch(20.7% 0.02 322.028)',
+          950: 'oklch(14.5% 0.008 322.12)'
+        }
+      }
+    },
+    colors: {
+      primary: 'pink',
+      secondary: 'violet',
+      neutral: 'saturated-mauve'
+    },
+    radius: 0.375,
+    font: { sans: 'Poppins' },
+    icons: 'phosphor',
+    tokens: {
+      light: {
+        '--ui-bg': 'var(--ui-color-neutral-50)',
+        '--ui-text-inverted': 'var(--ui-color-neutral-50)',
+        '--ui-bg-muted': 'var(--ui-color-neutral-100)'
+      },
+      dark: {
+        '--ui-bg-inverted': 'var(--ui-color-neutral-50)',
+        '--ui-text-highlighted': 'var(--ui-color-neutral-50)',
+        '--ui-border-inverted': 'var(--ui-color-neutral-50)'
+      }
+    }
+  }
+}, {
+  id: '8bit',
+  name: '8-bit',
+  description: 'Arcade red with pixel type and hard inked edges.',
+  icon: 'i-mdi-space-invaders',
+  doc: {
+    version: 1,
+    // Teal-washed neutral: the light end never reaches white, a dim LCD
+    // panel instead of paper.
+    palettes: {
+      crt: {
+        shades: {
+          50: 'oklch(89.7% 0.031 183.464)',
+          100: 'oklch(81.4% 0.049 184.157)',
+          200: 'oklch(72% 0.068 184.927)',
+          300: 'oklch(63% 0.077 185.803)',
+          400: 'oklch(55.3% 0.072 186.838)',
+          500: 'oklch(48.1% 0.062 188.141)',
+          600: 'oklch(41.2% 0.05 190.061)',
+          700: 'oklch(34.5% 0.038 193.49)',
+          800: 'oklch(27.8% 0.027 194.544)',
+          900: 'oklch(21.3% 0.015 194.783)',
+          950: 'oklch(14.8% 0.004 194.814)'
+        }
+      }
+    },
+    colors: {
+      primary: 'red',
+      neutral: 'crt'
+    },
+    radius: 0,
+    font: { sans: 'Pixelify Sans', weights: { normal: 400, medium: 500, semibold: 600, bold: 700 } },
+    icons: 'pixelarticons',
+    tokens: {
+      light: {
+        '--ui-primary': 'var(--ui-color-primary-600)',
+        '--ui-bg': 'var(--ui-color-neutral-50)',
+        '--ui-bg-muted': 'var(--ui-color-neutral-100)',
+        '--ui-bg-elevated': 'var(--ui-color-neutral-200)',
+        '--ui-text-inverted': 'var(--ui-color-neutral-50)',
+        '--ui-border': 'black',
+        '--ui-border-muted': 'var(--ui-color-neutral-300)',
+        '--ui-border-accented': 'black'
+      },
+      dark: {
+        '--ui-primary': 'var(--ui-color-primary-500)',
+        '--ui-bg-inverted': 'var(--ui-color-neutral-50)',
+        '--ui-text-highlighted': 'var(--ui-color-neutral-50)',
+        // the ink inverts in dark: an arcade outline is a bright edge there
+        '--ui-border': 'var(--ui-color-neutral-200)',
+        '--ui-border-accented': 'var(--ui-color-neutral-100)',
+        '--ui-border-inverted': 'var(--ui-color-neutral-50)'
+      }
+    },
+    style: {
+      // black is the neutral ladder's bottom stop, not a colour of its own
+      defaults: { variants: { panels: 'subtle' } }
+    }
+  }
+}, {
+  id: 'parchment',
+  name: 'Parchment',
+  description: 'Warm parchment neutrals with a book-cloth clay primary.',
+  icon: 'i-lucide-scroll-text',
+  doc: {
+    version: 1,
+    palettes: {
+      // Anchored on the real brand clay, hsl(14.8 63.1% 59.6%), at 500.
+      clay: {
+        shades: {
+          50: 'oklch(97.4% 0.009 48.308)',
+          100: 'oklch(94.2% 0.019 52.207)',
+          200: 'oklch(88.5% 0.036 51.142)',
+          300: 'oklch(82.1% 0.058 50.392)',
+          400: 'oklch(74.1% 0.094 47.255)',
+          500: 'oklch(67.2% 0.131 38.798)',
+          600: 'oklch(58.9% 0.138 37.63)',
+          700: 'oklch(51.4% 0.123 37.45)',
+          800: 'oklch(44.4% 0.103 36.916)',
+          900: 'oklch(38.8% 0.086 36.46)',
+          950: 'oklch(25.9% 0.054 38.197)'
+        }
+      },
+      // Their real --_gray-* stops mapped onto the tailwind ladder, the 50
+      // IS the signature cream background.
+      parchment: {
+        shades: {
+          50: 'oklch(98% 0.003 106.451)',
+          100: 'oklch(96.5% 0.004 106.469)',
+          200: 'oklch(93.6% 0.006 97.348)',
+          300: 'oklch(85.8% 0.014 102.476)',
+          400: 'oklch(72.1% 0.015 102.54)',
+          500: 'oklch(57.8% 0.008 88.877)',
+          600: 'oklch(43.2% 0.006 91.526)',
+          700: 'oklch(38.2% 0.003 84.572)',
+          800: 'oklch(29.3% 0.003 106.588)',
+          900: 'oklch(21.7% 0.002 106.561)',
+          950: 'oklch(14.6% 0 0)'
+        }
+      }
+    },
+    colors: {
+      primary: 'clay',
+      neutral: 'parchment'
+    },
+    radius: 0.375,
+    font: { sans: 'DM Sans', serif: 'Source Serif 4' },
+    icons: 'heroicons',
+    // Border family stepped one deeper to hold on the tinted cream page.
+    tokens: {
+      light: {
+        '--ui-bg': 'var(--ui-color-neutral-200)',
+        '--ui-bg-elevated': 'var(--ui-color-neutral-50)',
+        '--ui-bg-accented': 'var(--ui-color-neutral-300)',
+        '--ui-border': 'var(--ui-color-neutral-300)',
+        '--ui-border-accented': 'var(--ui-color-neutral-400)'
+      },
+      dark: {
+        '--ui-primary': 'var(--ui-color-primary-500)',
+        '--ui-bg-accented': 'var(--ui-color-neutral-800)'
+      }
+    },
+    style: {
+      defaults: { variants: { panels: 'subtle' } }
+    }
+  }
+}, {
+  id: 'signal',
+  name: 'Signal',
+  description: 'Dark-first ink surfaces, signal green, pill buttons.',
+  icon: 'i-lucide-audio-lines',
+  doc: {
+    version: 1,
+    palettes: {
+      signal: {
+        shades: {
+          50: 'oklch(97.3% 0.023 157.606)',
+          100: 'oklch(93.7% 0.051 157.559)',
+          200: 'oklch(88% 0.096 156.74)',
+          300: 'oklch(81.5% 0.14 155.469)',
+          400: 'oklch(75% 0.172 152.412)',
+          500: 'oklch(68.9% 0.187 148.921)',
+          600: 'oklch(60.7% 0.165 149.023)',
+          700: 'oklch(52.9% 0.141 149.561)',
+          800: 'oklch(44.9% 0.115 150.596)',
+          900: 'oklch(38.7% 0.095 151.748)',
+          950: 'oklch(25.6% 0.058 153.065)'
+        }
+      },
+      ink: {
+        shades: {
+          50: 'oklch(97.9% 0 0)',
+          100: 'oklch(95.2% 0 0)',
+          200: 'oklch(90.1% 0 0)',
+          300: 'oklch(76.7% 0 0)',
+          400: 'oklch(65% 0 0)',
+          500: 'oklch(53.8% 0 0)',
+          600: 'oklch(44.2% 0 0)',
+          700: 'oklch(37.1% 0 0)',
+          800: 'oklch(28.5% 0 0)',
+          900: 'oklch(20.9% 0 0)',
+          950: 'oklch(18.2% 0 0)'
+        }
+      }
+    },
+    colors: {
+      primary: 'signal',
+      neutral: 'ink'
+    },
+    radius: 0.5,
+    font: { sans: 'DM Sans' },
+    icons: 'material',
+    tokens: {
+      dark: {
+        '--ui-bg': 'var(--ui-color-neutral-950)',
+        '--ui-bg-muted': 'var(--ui-color-neutral-900)'
+      }
+    },
+    components: {
+      button: {
+        slots: {
+          base: 'rounded-full'
+        }
+      }
+    }
+  }
+}, {
+  id: 'cobalt',
+  name: 'Cobalt',
+  description: 'Utility blue on cool grays, tight corners, flat bordered surfaces.',
+  icon: 'i-lucide-gem',
+  doc: {
+    version: 1,
+    // The real 5.3 tint/shade-color() scales, extended to 50/950 with the
+    // same math. Prefixed names: a palette named plainly 'blue'/'gray' would
+    // override the same-named tailwind ramp app-wide while active.
+    palettes: {
+      'cobalt': {
+        shades: {
+          50: 'oklch(95.3% 0.022 260.723)',
+          100: 'oklch(90.8% 0.045 258.763)',
+          200: 'oklch(81.6% 0.091 257.776)',
+          300: 'oklch(72.9% 0.14 258.068)',
+          400: 'oklch(64.7% 0.186 258.256)',
+          500: 'oklch(57.8% 0.228 260.025)',
+          600: 'oklch(49.2% 0.19 259.799)',
+          700: 'oklch(40.2% 0.152 259.656)',
+          800: 'oklch(30.7% 0.109 258.934)',
+          900: 'oklch(20.4% 0.063 257.52)',
+          950: 'oklch(14.7% 0.037 249.929)'
+        }
+      },
+      // $gray-100…$gray-900 verbatim, with 50/950 extrapolated.
+      'cobalt-gray': {
+        shades: {
+          50: 'oklch(99.1% 0 0)',
+          100: 'oklch(98.2% 0.002 247.839)',
+          200: 'oklch(94.2% 0.005 247.879)',
+          300: 'oklch(91.1% 0.007 247.901)',
+          400: 'oklch(86.7% 0.011 247.949)',
+          500: 'oklch(76.9% 0.015 248.017)',
+          600: 'oklch(55.8% 0.016 244.893)',
+          700: 'oklch(42.8% 0.015 248.172)',
+          800: 'oklch(34.5% 0.013 248.212)',
+          900: 'oklch(26.2% 0.009 248.19)',
+          950: 'oklch(20.7% 0.008 248.192)'
+        }
+      },
+      'bs-green': {
+        shades: {
+          50: 'oklch(95.5% 0.013 167.173)',
+          100: 'oklch(90.9% 0.027 166.725)',
+          200: 'oklch(81.7% 0.054 165.592)',
+          300: 'oklch(72.6% 0.082 163.174)',
+          400: 'oklch(63.7% 0.106 160.921)',
+          500: 'oklch(55.2% 0.123 157.012)',
+          600: 'oklch(47.1% 0.104 157.226)',
+          700: 'oklch(38.6% 0.083 157.541)',
+          800: 'oklch(29.7% 0.06 159.192)',
+          900: 'oklch(20% 0.035 161.761)',
+          950: 'oklch(14.4% 0.023 167.139)'
+        }
+      },
+      'bs-red': {
+        shades: {
+          50: 'oklch(95.4% 0.019 13.379)',
+          100: 'oklch(90.7% 0.037 11.626)',
+          200: 'oklch(81.5% 0.079 12.026)',
+          300: 'oklch(73% 0.123 14.804)',
+          400: 'oklch(65.2% 0.167 17.173)',
+          500: 'oklch(59.2% 0.202 21.239)',
+          600: 'oklch(50.2% 0.17 20.933)',
+          700: 'oklch(41% 0.134 20.765)',
+          800: 'oklch(31.2% 0.097 19.17)',
+          900: 'oklch(20.7% 0.055 17.828)',
+          950: 'oklch(14.7% 0.033 12.672)'
+        }
+      },
+      'bs-yellow': {
+        shades: {
+          50: 'oklch(98.2% 0.026 92.389)',
+          100: 'oklch(96.4% 0.051 92.554)',
+          200: 'oklch(92.9% 0.097 91.534)',
+          300: 'oklch(89.8% 0.137 91.178)',
+          400: 'oklch(86.9% 0.162 88.789)',
+          500: 'oklch(84.4% 0.172 84.934)',
+          600: 'oklch(71.4% 0.145 85.028)',
+          700: 'oklch(58% 0.118 86.024)',
+          800: 'oklch(43.5% 0.088 86.646)',
+          900: 'oklch(27.9% 0.056 90.569)',
+          950: 'oklch(18.9% 0.036 93.534)'
+        }
+      },
+      'bs-cyan': {
+        shades: {
+          50: 'oklch(97.2% 0.021 211.758)',
+          100: 'oklch(94.3% 0.04 212.228)',
+          200: 'oklch(89.3% 0.077 211.321)',
+          300: 'oklch(84.6% 0.107 212.793)',
+          400: 'oklch(80.8% 0.129 214.292)',
+          500: 'oklch(77.5% 0.138 218.055)',
+          600: 'oklch(65.8% 0.116 217.451)',
+          700: 'oklch(53.2% 0.094 217.564)',
+          800: 'oklch(40.1% 0.07 216.209)',
+          900: 'oklch(25.6% 0.043 215.657)',
+          950: 'oklch(17.6% 0.029 211.647)'
+        }
+      }
+    },
+    // secondary is literally $gray-600, so the gray ramp serves both roles.
+    colors: {
+      primary: 'cobalt',
+      secondary: 'cobalt-gray',
+      success: 'bs-green',
+      info: 'bs-cyan',
+      warning: 'bs-yellow',
+      error: 'bs-red',
+      neutral: 'cobalt-gray'
+    },
+    radius: 0.125,
+    // Bootstrap ships the system-ui stack; Roboto is its named Android
+    // fallback and the closest loadable stand-in.
+    font: { sans: 'Roboto' },
+    icons: 'bootstrap',
+    // Light rides the gray ramp one step deeper than stock.
+    tokens: {
+      light: {
+        '--ui-secondary': 'var(--ui-color-secondary-600)',
+        '--ui-bg-muted': 'var(--ui-color-neutral-200)',
+        '--ui-text': 'var(--ui-color-neutral-800)',
+        '--ui-border': 'var(--ui-color-neutral-400)',
+        '--ui-border-muted': 'var(--ui-color-neutral-300)',
+        '--ui-bg': 'var(--ui-color-neutral-100)',
+        '--ui-text-toned': 'var(--ui-color-neutral-700)',
+        '--ui-text-muted': 'var(--ui-color-neutral-600)',
+        '--ui-text-dimmed': 'var(--ui-color-neutral-600)',
+        '--ui-bg-elevated': 'var(--ui-color-neutral-200)',
+        '--ui-bg-accented': 'var(--ui-color-neutral-300)'
+      },
+      // Dark keeps the same brand colors (--bs-primary stays #0d6efd);
+      // $body-color-dark: $gray-300.
+      dark: {
+        '--ui-primary': 'var(--ui-color-primary-500)',
+        '--ui-secondary': 'var(--ui-color-secondary-500)',
+        '--ui-success': 'var(--ui-color-success-500)',
+        '--ui-info': 'var(--ui-color-info-500)',
+        '--ui-warning': 'var(--ui-color-warning-500)',
+        '--ui-error': 'var(--ui-color-error-500)',
+        '--ui-bg-muted': 'var(--ui-color-neutral-700)',
+        '--ui-text': 'var(--ui-color-neutral-300)'
+      }
+    }
+  }
+}] satisfies ThemePreset[]
diff --git a/docs/app/utils/theme/engine/sections.ts b/docs/app/utils/theme/engine/sections.ts
new file mode 100644
index 0000000000..25dbedd7b4
--- /dev/null
+++ b/docs/app/utils/theme/engine/sections.ts
@@ -0,0 +1,286 @@
+import type { ThemeDoc, ShadeStop, StyleOptions } from './types'
+import { DEFAULT_COLORS, THEME_DEFAULTS, SEMANTIC_ALIASES, styleTokens, TOKEN_SHADE_TARGETS, parseUiColorRef } from './types'
+import { FONT_WEIGHT_DEFAULTS } from '../studio'
+
+/**
+ * The studio's setting sections, each owning a slice of the ThemeDoc.
+ * `pickSection` extracts a section's normalized state ("absent" and
+ * "explicitly stock" compare equal); `mergeSection` splices one doc's slice
+ * into another, which is all a per-section reset is. The baseline is the
+ * ACTIVE PRESET's doc: dirty means "touched after applying the preset", not
+ * "differs from stock".
+ */
+export type SectionKey
+  = | 'primary' | 'neutral' | 'semantic'
+    | 'font' | 'icons' | 'radius' | 'size' | 'buttons' | 'panels' | 'inputs'
+
+/**
+ * Only the two that still back a multi-section panel. Type, icons and radius
+ * each own a toolbar control now, so they carry their own `sectionDirty`
+ * rather than rolling up into a group.
+ */
+export const SECTION_GROUPS: Record<'colors' | 'defaults', SectionKey[]> = {
+  colors: ['primary', 'neutral', 'semantic'],
+  defaults: ['size', 'buttons', 'panels', 'inputs']
+}
+
+/** Which color section a semantic token (or token shade) belongs to. */
+function tokenSection(token: string): 'primary' | 'semantic' | 'neutral' {
+  if (token === '--ui-primary' || token.startsWith('--ui-color-primary')) return 'primary'
+  if (SEMANTIC_ALIASES.some(alias => token === `--ui-${alias}`)) return 'semantic'
+  return 'neutral'
+}
+
+/**
+ * applyDoc promotes ramp-shaped token overrides into style.tokenShades, so a
+ * live doc and its preset express the SAME choice in different slots, both
+ * sides compare canonicalized: promotable tokens count as shades.
+ */
+export function promotedShades(doc: ThemeDoc): Record<string, { light?: ShadeStop, dark?: ShadeStop }> {
+  const promoted: Record<string, { light?: ShadeStop, dark?: ShadeStop }> = {}
+  const parse = (value: string | undefined, ramp: string) => {
+    const ref = parseUiColorRef(value)
+    return ref?.alias === ramp ? ref.shade as ShadeStop : undefined
+  }
+  for (const target of TOKEN_SHADE_TARGETS) {
+    if (doc.style?.tokenShades?.[target.token]) continue
+    const light = parse(doc.tokens?.light?.[target.token], target.ramp)
+    const dark = parse(doc.tokens?.dark?.[target.token], target.ramp)
+    if (light !== undefined || dark !== undefined) {
+      promoted[target.token] = { ...(light !== undefined ? { light } : {}), ...(dark !== undefined ? { dark } : {}) }
+    }
+  }
+  return promoted
+}
+
+function ownedTokens(doc: ThemeDoc, section: 'primary' | 'semantic' | 'neutral') {
+  // tokens the doc's own style treatment emits are DERIVED, a live doc
+  // carries them merged into tokens, a preset doc never does
+  const derived = styleTokens(doc.style ?? {})
+  const promoted = promotedShades(doc)
+  const pickMode = (mode: 'light' | 'dark') =>
+    Object.fromEntries(Object.entries(doc.tokens?.[mode] ?? {})
+      .filter(([token]) => !(token in derived[mode])
+        && promoted[token]?.[mode] === undefined
+        && tokenSection(token) === section))
+  return { light: pickMode('light'), dark: pickMode('dark') }
+}
+
+function ownedTokenShades(doc: ThemeDoc, section: 'primary' | 'semantic' | 'neutral') {
+  return Object.fromEntries(Object.entries(canonicalTokenShades(doc)).filter(([token]) => tokenSection(token) === section))
+}
+
+function alias(doc: ThemeDoc, name: keyof typeof DEFAULT_COLORS): string {
+  return doc.colors?.[name] ?? DEFAULT_COLORS[name]
+}
+
+/** The custom ramp an alias references, if the doc carries one. */
+function aliasPalette(doc: ThemeDoc, name: keyof typeof DEFAULT_COLORS) {
+  return doc.palettes?.[alias(doc, name)]
+}
+
+type VariantGroupKey = 'buttons' | 'panels' | 'inputs'
+
+function groupPick(doc: ThemeDoc, group: VariantGroupKey) {
+  const defaults = doc.style?.defaults
+  return {
+    // effective variant: the group's own choice, else the app-wide fallback
+    variant: defaults?.variants?.[group] ?? defaults?.variant ?? null,
+    color: defaults?.colors?.[group] ?? null
+  }
+}
+
+export function pickSection(doc: ThemeDoc, key: SectionKey): unknown {
+  const style: StyleOptions = doc.style ?? {}
+  switch (key) {
+    case 'primary':
+      return {
+        color: doc.blackAsPrimary ? 'black' : alias(doc, 'primary'),
+        palette: aliasPalette(doc, 'primary') ?? null,
+        tokens: ownedTokens(doc, 'primary'),
+        shades: ownedTokenShades(doc, 'primary')
+      }
+    case 'neutral':
+      return {
+        color: alias(doc, 'neutral'),
+        palette: aliasPalette(doc, 'neutral') ?? null,
+        tokens: ownedTokens(doc, 'neutral'),
+        shades: ownedTokenShades(doc, 'neutral')
+      }
+    case 'semantic':
+      return {
+        colors: Object.fromEntries(SEMANTIC_ALIASES.map(name => [name, alias(doc, name)])),
+        palettes: Object.fromEntries(SEMANTIC_ALIASES.map(name => [name, aliasPalette(doc, name) ?? null])),
+        tokens: ownedTokens(doc, 'semantic'),
+        shades: ownedTokenShades(doc, 'semantic')
+      }
+    case 'font': {
+      // Explicit stock values count as absent: setFontPrefs strips them on
+      // apply while a preset doc may spell them out (8-bit), raw comparison
+      // would read dirty forever, jamming the toolbar reset.
+      const font = { ...(doc.font ?? {}) }
+      const weights = Object.fromEntries(Object.entries(font.weights ?? {})
+        .filter(([step, weight]) => weight !== FONT_WEIGHT_DEFAULTS[step as keyof typeof FONT_WEIGHT_DEFAULTS]))
+      if (Object.keys(weights).length) font.weights = weights as typeof font.weights
+      else delete font.weights
+      if (font.letterSpacing === 0) delete font.letterSpacing
+      if (font.lineHeight === 1.5) delete font.lineHeight
+      // size lives in the type panel, so the type section owns it
+      return { ...font, size: doc.fontSize ?? THEME_DEFAULTS.fontSize }
+    }
+    case 'icons':
+      return doc.icons ?? THEME_DEFAULTS.icons
+    case 'radius':
+      return doc.radius ?? THEME_DEFAULTS.radius
+    case 'size':
+      return style.defaults?.size ?? null
+    case 'buttons':
+    case 'panels':
+    case 'inputs':
+      return groupPick(doc, key)
+  }
+}
+
+/** Stable stringify (sorted keys) so pick results compare structurally. */
+export function sectionFingerprint(doc: ThemeDoc, key: SectionKey): string {
+  const sort = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(sort)
+    if (value && typeof value === 'object') {
+      return Object.fromEntries(Object.keys(value).sort().map(k => [k, sort((value as Record<string, unknown>)[k])]))
+    }
+    return value
+  }
+  return JSON.stringify(sort(pickSection(doc, key)))
+}
+
+/**
+ * A doc's effective per-token shade choices: explicit style.tokenShades plus
+ * ramp-shaped token overrides. Per-row shade resets restore THESE.
+ */
+export function canonicalTokenShades(doc: ThemeDoc): Record<string, { light?: ShadeStop, dark?: ShadeStop }> {
+  return { ...promotedShades(doc), ...doc.style?.tokenShades }
+}
+
+/* --------------------------------------------------------------- merge -- */
+
+function setOrDelete<T extends object, K extends keyof T>(target: T, key: K, value: T[K] | undefined) {
+  if (value === undefined) Reflect.deleteProperty(target, key)
+  else target[key] = value
+}
+
+function pruneEmpty(doc: ThemeDoc) {
+  for (const key of ['colors', 'palettes', 'style'] as const) {
+    if (doc[key] && !Object.keys(doc[key]!).length) Reflect.deleteProperty(doc, key)
+  }
+  if (doc.tokens) {
+    for (const mode of ['light', 'dark'] as const) {
+      if (doc.tokens[mode] && !Object.keys(doc.tokens[mode]!).length) Reflect.deleteProperty(doc.tokens, mode)
+    }
+    if (!Object.keys(doc.tokens).length) delete doc.tokens
+  }
+  if (doc.style?.defaults) {
+    for (const key of ['variants', 'colors'] as const) {
+      if (doc.style.defaults[key] && !Object.keys(doc.style.defaults[key]!).length) Reflect.deleteProperty(doc.style.defaults, key)
+    }
+    if (!Object.keys(doc.style.defaults).length) delete doc.style.defaults
+  }
+  if (doc.style?.tokenShades && !Object.keys(doc.style.tokenShades).length) delete doc.style.tokenShades
+}
+
+/** Replace one alias's color + referenced palette with the base doc's. */
+function mergeAlias(doc: ThemeDoc, base: ThemeDoc, name: keyof typeof DEFAULT_COLORS) {
+  const currentPaletteName = alias(doc, name)
+  if (doc.palettes) Reflect.deleteProperty(doc.palettes, currentPaletteName)
+
+  doc.colors ??= {}
+  setOrDelete(doc.colors, name, base.colors?.[name])
+
+  const basePalette = aliasPalette(base, name)
+  if (basePalette) {
+    doc.palettes ??= {}
+    doc.palettes[alias(base, name)] = structuredClone(basePalette)
+  }
+}
+
+/** Swap a color section's tokens/token-shades for the base doc's. */
+function mergeColorExtras(doc: ThemeDoc, base: ThemeDoc, section: 'primary' | 'semantic' | 'neutral') {
+  for (const mode of ['light', 'dark'] as const) {
+    const kept = Object.entries(doc.tokens?.[mode] ?? {}).filter(([token]) => tokenSection(token) !== section)
+    const added = Object.entries(base.tokens?.[mode] ?? {}).filter(([token]) => tokenSection(token) === section)
+    const merged = Object.fromEntries([...kept, ...added])
+    if (Object.keys(merged).length) {
+      doc.tokens ??= {}
+      doc.tokens[mode] = merged
+    } else if (doc.tokens) {
+      Reflect.deleteProperty(doc.tokens, mode)
+    }
+  }
+  const keptShades = Object.entries(doc.style?.tokenShades ?? {}).filter(([token]) => tokenSection(token) !== section)
+  const addedShades = Object.entries(base.style?.tokenShades ?? {}).filter(([token]) => tokenSection(token) === section)
+  const mergedShades = Object.fromEntries([...keptShades, ...addedShades])
+  if (Object.keys(mergedShades).length) {
+    doc.style ??= {}
+    doc.style.tokenShades = mergedShades as StyleOptions['tokenShades']
+  } else if (doc.style) {
+    delete doc.style.tokenShades
+  }
+}
+
+/**
+ * A new doc with `key`'s slice taken from `base` and everything else from
+ * `current`, apply it and the section is reset to the baseline.
+ */
+export function mergeSection(current: ThemeDoc, base: ThemeDoc, key: SectionKey): ThemeDoc {
+  const doc = structuredClone(current)
+  doc.style = doc.style ? structuredClone(doc.style) : undefined
+  const baseStyle: StyleOptions = base.style ?? {}
+
+  switch (key) {
+    case 'primary':
+      setOrDelete(doc, 'blackAsPrimary', base.blackAsPrimary || undefined)
+      mergeAlias(doc, base, 'primary')
+      mergeColorExtras(doc, base, 'primary')
+      break
+    case 'neutral':
+      mergeAlias(doc, base, 'neutral')
+      mergeColorExtras(doc, base, 'neutral')
+      break
+    case 'semantic':
+      for (const name of SEMANTIC_ALIASES) mergeAlias(doc, base, name)
+      mergeColorExtras(doc, base, 'semantic')
+      break
+    case 'font':
+      setOrDelete(doc, 'font', base.font ? structuredClone(base.font) : undefined)
+      setOrDelete(doc, 'fontSize', base.fontSize)
+      break
+    case 'icons':
+      setOrDelete(doc, 'icons', base.icons)
+      break
+    case 'radius':
+      setOrDelete(doc, 'radius', base.radius)
+      break
+    case 'size':
+      if (doc.style?.defaults || baseStyle.defaults?.size !== undefined) {
+        doc.style ??= {}
+        doc.style.defaults = { ...doc.style.defaults }
+        setOrDelete(doc.style.defaults, 'size', baseStyle.defaults?.size)
+      }
+      break
+    case 'buttons':
+    case 'panels':
+    case 'inputs':
+      if (doc.style?.defaults || baseStyle.defaults) {
+        doc.style ??= {}
+        doc.style.defaults = { ...doc.style.defaults }
+        doc.style.defaults.variants = { ...doc.style.defaults.variants }
+        doc.style.defaults.colors = { ...doc.style.defaults.colors }
+        setOrDelete(doc.style.defaults.variants, key, baseStyle.defaults?.variants?.[key])
+        setOrDelete(doc.style.defaults.colors, key, baseStyle.defaults?.colors?.[key])
+      }
+      break
+  }
+
+  if (doc.style === undefined) delete doc.style
+  pruneEmpty(doc)
+  return doc
+}
diff --git a/docs/app/utils/theme/engine/serialize.ts b/docs/app/utils/theme/engine/serialize.ts
new file mode 100644
index 0000000000..59e8a091cf
--- /dev/null
+++ b/docs/app/utils/theme/engine/serialize.ts
@@ -0,0 +1,719 @@
+/**
+ * The theme's wire format, both directions.
+ *
+ * `generateCSS`/`generateConfig` emit the minimal `main.css` +
+ * `app.config.ts` pair for a doc; `importTheme` parses that pair back. They
+ * are a contract, not two independent modules: any change to what the
+ * emitters print needs a matching change to the grammar the parser accepts,
+ * or a theme stops round-tripping. They live together so that drift is
+ * visible in one diff.
+ */
+import type { ThemeDoc, Shade, StyleOptions, DefaultVariant, DefaultSize, DefaultColor, VariantGroup } from './types'
+import {
+  SHADES_ALL,
+  DEFAULT_COLORS,
+  THEME_DEFAULTS,
+  LIBRARY_TOKEN_DEFAULTS,
+  styleComponents,
+  styleTokens,
+  mergeUi,
+  VARIANT_GROUPS,
+  VARIANT_SUPPORT,
+  SIZE_SUPPORT,
+  COLOR_SUPPORT
+} from './types'
+import { themeIcons } from '../icons'
+
+/* ======================================================== emit (export) == */
+
+/** Generate the minimal `main.css`, the doc only holds overrides, so everything present is emitted. */
+export function generateCSS(doc: ThemeDoc): string {
+  const lines = [
+    '@import "tailwindcss";',
+    '@import "@nuxt/ui";'
+  ]
+
+  const themeLines: string[] = []
+  if (doc.font?.sans && doc.font.sans !== THEME_DEFAULTS.font) {
+    themeLines.push(`  --font-sans: '${doc.font.sans}', sans-serif;`)
+  }
+  // Tailwind's own stacks: setting them is all `font-serif` / `font-mono` need.
+  if (doc.font?.serif) themeLines.push(`  --font-serif: '${doc.font.serif}', serif;`)
+  if (doc.font?.mono) themeLines.push(`  --font-mono: '${doc.font.mono}', monospace;`)
+  // Weight steps are live variables in tailwind v4, so remapping them
+  // reaches every component, not just inherited text.
+  for (const step of ['normal', 'medium', 'semibold', 'bold'] as const) {
+    const weight = doc.font?.weights?.[step]
+    if (weight !== undefined) {
+      themeLines.push(`  --font-weight-${step}: ${weight};`)
+    }
+  }
+  if (themeLines.length) {
+    lines.push('', '@theme {', ...themeLines, '}')
+  }
+
+  const colorLines: string[] = []
+  for (const [name, palette] of Object.entries(doc.palettes || {})) {
+    for (const [shade, color] of Object.entries(palette.shades)) {
+      colorLines.push(`  --color-${name}-${shade}: ${color};`)
+    }
+  }
+
+  if (colorLines.length) {
+    lines.push('', '@theme static {', ...colorLines, '}')
+  }
+
+  if (doc.fontSize !== undefined && doc.fontSize !== THEME_DEFAULTS.fontSize) {
+    lines.push('', '@layer base {', '  html {', `    font-size: ${doc.fontSize}px;`, '  }', '}')
+  }
+
+  // Classless text has no utility to dereference the weight variable, and
+  // case/tracking/leading are inherited properties. These element rules ride
+  // `@layer base`: unlayered CSS outranks every layer, so a bare rule here
+  // would beat the utilities too and `<h1 class="font-mono">` could not
+  // override the heading family. In base they still beat preflight (same
+  // layer, later source order) while utilities keep winning.
+  const bodyLines: string[] = []
+  if (doc.font?.weights?.normal !== undefined) bodyLines.push(`  font-weight: ${doc.font.weights.normal};`)
+  if (doc.font?.uppercase) bodyLines.push('  text-transform: uppercase;')
+  if (doc.font?.italic) bodyLines.push('  font-style: italic;')
+  if (doc.font?.letterSpacing !== undefined) bodyLines.push(`  letter-spacing: ${doc.font.letterSpacing}em;`)
+  if (doc.font?.lineHeight !== undefined) bodyLines.push(`  line-height: ${doc.font.lineHeight};`)
+  if (bodyLines.length) {
+    lines.push('', '@layer base {', '  body {', ...bodyLines.map(line => `  ${line}`), '  }', '}')
+  }
+
+  // Sans and mono ride tailwind's preflight (`--default-font-family` and
+  // `--default-mono-font-family`), so neither needs a rule. Nothing consumes
+  // `--font-serif`, so headings get this one, emitted only when a serif is
+  // set: without the guard, picking just a sans would drop every heading to
+  // Georgia. A stopgap until v5's `--ui-font-heading`.
+  if (doc.font?.serif) {
+    lines.push('', '/* until v5 ships --ui-font-heading */', '@layer base {', '  h1, h2, h3, h4, h5, h6 {', '    font-family: var(--font-serif);', '  }', '}')
+  }
+
+  const rootLines: string[] = []
+  if (doc.radius !== undefined && doc.radius !== THEME_DEFAULTS.radius) {
+    rootLines.push(`  --ui-radius: ${doc.radius}rem;`)
+  }
+  if (doc.blackAsPrimary) {
+    rootLines.push('  --ui-primary: black;')
+  }
+
+  if (rootLines.length) {
+    lines.push('', ':root {', ...rootLines, '}')
+  }
+
+  // Semantic token shades behind the style choices.
+  const style = styleTokens(doc.style || {})
+  // Style expansion and explicit token overrides merge, explicit last so a
+  // round-tripped doc collapses instead of printing every variable twice.
+  const light = { ...style.light, ...doc.tokens?.light }
+
+  const dark: Record<string, string> = {
+    ...style.dark,
+    ...(doc.blackAsPrimary ? { '--ui-primary': 'white' } : {}),
+    ...doc.tokens?.dark
+  }
+  // `:root, .light` matches `<html class="dark">` too and lands after the
+  // library's `.dark` block, so a light-only override would win in dark mode.
+  // Restate the library's dark value so the `.dark` block wins it back.
+  for (const [key, value] of Object.entries(light)) {
+    if (key in dark) continue
+    const fallback = (LIBRARY_TOKEN_DEFAULTS.dark as Record<string, string>)[key]
+    if (fallback && fallback !== value) {
+      dark[key] = fallback
+    }
+  }
+
+  if (Object.keys(light).length) {
+    lines.push('', ':root, .light {', ...Object.entries(light).map(([key, val]) => `  ${key}: ${val};`), '}')
+  }
+
+  if (Object.keys(dark).length) {
+    lines.push('', '.dark {', ...Object.entries(dark).map(([key, val]) => `  ${key}: ${val};`), '}')
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Serialize to JS object-literal source: unquote only identifier-safe keys,
+ * prefer single-quoted strings, keep double quotes around apostrophes.
+ */
+function toObjectSource(value: Record<string, any>): string {
+  return JSON.stringify(value, null, 2)
+    .replace(/"([a-z_$][\w$]*)":/gi, '$1:')
+    .replace(/"((?:[^"\\]|\\.)*)"/g, (match, body: string) =>
+      body.includes('\'') ? match : `'${body}'`)
+}
+
+/** The `app.config.ts` / `vite.config.ts` side of the export. */
+export function generateConfig(doc: ThemeDoc, framework: string = 'nuxt'): string {
+  const config: Record<string, any> = {}
+
+  const colorEntries = Object.entries(doc.colors || {}).filter(([key, value]) => value !== DEFAULT_COLORS[key as keyof typeof DEFAULT_COLORS])
+  if (colorEntries.length) {
+    config.ui = { colors: Object.fromEntries(colorEntries) }
+  }
+
+  if (doc.icons && doc.icons !== THEME_DEFAULTS.icons && doc.icons in themeIcons) {
+    config.ui = config.ui || {}
+    config.ui.icons = themeIcons[doc.icons as keyof typeof themeIcons]
+  }
+
+  // Explicit components merge INTO the style expansion (classes concatenate,
+  // explicit last), a spread would drop one side wholesale.
+  const componentOverrides = mergeUi(doc.style ? styleComponents(doc.style) : undefined, doc.components)
+  if (Object.keys(componentOverrides).length) {
+    config.ui = config.ui || {}
+    Object.assign(config.ui, componentOverrides)
+  }
+
+  const configString = toObjectSource(config)
+
+  if (framework === 'vue') {
+    const pluginConfig = config.ui
+      ? toObjectSource({ ui: config.ui })
+      : '{}'
+    return [
+      'import { defineConfig } from \'vite\'',
+      'import vue from \'@vitejs/plugin-vue\'',
+      'import ui from \'@nuxt/ui/vite\'',
+      '',
+      `export default defineConfig({`,
+      '  plugins: [',
+      '    vue(),',
+      `    ui(${pluginConfig.split('\n').map((line, i) => i === 0 ? line : '    ' + line).join('\n')})`,
+      '  ]',
+      '})'
+    ].join('\n')
+  }
+
+  return `export default defineAppConfig(${configString})`
+}
+
+/**
+ * Translate a document into the shape `applyThemeSettings()` accepts, the
+ * sanitized write path shared with the AI theme feature.
+ */
+export function docToSettings(doc: ThemeDoc): Record<string, any> {
+  const settings: Record<string, any> = {}
+
+  for (const [alias, palette] of Object.entries(doc.colors || {})) {
+    settings[alias] = palette
+  }
+
+  if (doc.blackAsPrimary) settings.blackAsPrimary = true
+  if (doc.radius !== undefined) settings.radius = doc.radius
+  if (doc.fontSize !== undefined) settings.fontSize = doc.fontSize
+  if (doc.font?.sans) settings.fontSans = doc.font.sans
+  if (doc.font?.serif) settings.fontSerif = doc.font.serif
+  if (doc.font?.mono) settings.fontMono = doc.font.mono
+  if (doc.font?.weights) settings.fontWeights = doc.font.weights
+  if (doc.font?.uppercase || doc.font?.italic || doc.font?.letterSpacing !== undefined || doc.font?.lineHeight !== undefined) {
+    settings.fontBody = { uppercase: doc.font.uppercase, italic: doc.font.italic, letterSpacing: doc.font.letterSpacing, lineHeight: doc.font.lineHeight }
+  }
+  if (doc.icons) settings.icons = doc.icons
+
+  if (doc.palettes) {
+    settings.customColors = Object.fromEntries(
+      Object.entries(doc.palettes).map(([name, palette]) => [name, palette.shades])
+    )
+  }
+
+  // Token overrides plus the style treatment's color variables.
+  const style = doc.style ? styleTokens(doc.style) : { light: {}, dark: {} }
+  const light = { ...style.light, ...doc.tokens?.light }
+  const dark = { ...style.dark, ...doc.tokens?.dark }
+  if (Object.keys(light).length || Object.keys(dark).length) {
+    settings.cssVariables = {
+      ...(Object.keys(light).length ? { light } : {}),
+      ...(Object.keys(dark).length ? { dark } : {})
+    }
+  }
+
+  // Only explicit components ride the settings channel, the style expansion
+  // goes through the dedicated style-ui channel (applyDoc).
+  if (doc.components && Object.keys(doc.components).length) {
+    settings.ui = doc.components
+  }
+
+  return settings
+}
+
+/* ====================================================== parse (import) == */
+
+/**
+ * The inverse of generateCSS/generateConfig: parse an exported theme back
+ * into a ThemeDoc. Anything outside the export grammar is collected in
+ * `skipped` and surfaced, never silently dropped.
+ */
+export interface ThemeImportResult {
+  doc: ThemeDoc
+  skipped: string[]
+}
+
+const SHADE_SET = new Set<number>(SHADES_ALL)
+
+/* ---------------------------------------------------------------- CSS -- */
+
+interface ParsedCSS {
+  palettes: Record<string, Partial<Record<Shade, string>>>
+  font?: string
+  fontSize?: number
+  radius?: number
+  fontWeights?: { normal?: number, medium?: number, semibold?: number, bold?: number }
+  body?: { weight?: number, uppercase?: boolean, italic?: boolean, letterSpacing?: number, lineHeight?: number }
+  serif?: string
+  mono?: string
+  blackAsPrimary?: boolean
+  light: Record<string, string>
+  dark: Record<string, string>
+  skipped: string[]
+}
+
+function parseCSS(css: string): ParsedCSS {
+  const result: ParsedCSS = { palettes: {}, light: {}, dark: {}, skipped: [] }
+  let clean = css.replace(/\/\*[\s\S]*?\*\//g, '')
+
+  // Our own export wraps the element rules in `@layer base` (so utilities can
+  // still win); unwrap that one layer so the flat scanner below sees them.
+  clean = clean.replace(/@layer\s+base\s*\{((?:[^{}]*\{[^{}]*\})*)\s*\}/g, '$1')
+
+  // The flat block scanner can't see nesting, a nested at-rule's inner
+  // blocks would import as GLOBAL tokens. Lift each whole one into `skipped`.
+  clean = clean.replace(/@(?:media|supports|container|layer|scope)[^{}]*\{(?:[^{}]*\{[^{}]*\})*[^{}]*\}/g, (block) => {
+    result.skipped.push(block.trim().replace(/\s+/g, ' '))
+    return ''
+  })
+
+  const blockRe = /([^{}]+)\{([^{}]*)\}/g
+  let cursor = 0
+  let match: RegExpExecArray | null
+
+  const outside = (text: string) => {
+    for (const line of text.split('\n')) {
+      const trimmed = line.trim()
+      if (trimmed && !trimmed.startsWith('@import') && !trimmed.startsWith('@source')) {
+        result.skipped.push(trimmed)
+      }
+    }
+  }
+
+  while ((match = blockRe.exec(clean))) {
+    cursor = match.index + match[0].length
+
+    // The selector is what follows the last ';'; the rest is preamble.
+    const segments = match[1]!.split(';')
+    outside(segments.slice(0, -1).join('\n'))
+    const selector = segments[segments.length - 1]!.trim().replace(/\s+/g, ' ')
+    const declarations = match[2]!.split(';')
+      .map(declaration => declaration.trim())
+      .filter(Boolean)
+      .map((declaration) => {
+        const colon = declaration.indexOf(':')
+        return [declaration.slice(0, colon).trim(), declaration.slice(colon + 1).trim()] as const
+      })
+
+    for (const [prop, value] of declarations) {
+      if (!parseDeclaration(result, selector, prop, value)) {
+        result.skipped.push(`${selector} { ${prop}: ${value} }`)
+      }
+    }
+  }
+  outside(clean.slice(cursor))
+
+  return result
+}
+
+function parseDeclaration(result: ParsedCSS, selector: string, prop: string, value: string): boolean {
+  if (selector === '@theme static' || selector === '@theme') {
+    const shade = prop.match(/^--color-(.+)-(\d{2,3})$/)
+    if (shade && SHADE_SET.has(Number(shade[2]))) {
+      const palette = result.palettes[shade[1]!] ||= {}
+      palette[Number(shade[2]) as Shade] = value
+      return true
+    }
+    const stack = prop.match(/^--font-(sans|serif|mono)$/)
+    if (stack) {
+      const family = value.match(/^'([^']+)'/) || value.match(/^"([^"]+)"/)
+      if (family) {
+        if (stack[1] === 'sans') result.font = family[1]
+        else if (stack[1] === 'serif') result.serif = family[1]
+        else result.mono = family[1]
+        return true
+      }
+    }
+    const weightStep = prop.match(/^--font-weight-(normal|medium|semibold|bold)$/)
+    if (weightStep && /^\d+$/.test(value)) {
+      result.fontWeights = { ...result.fontWeights, [weightStep[1]!]: Number(value) }
+      return true
+    }
+    return false
+  }
+
+  if (selector === 'html' && prop === 'font-size' && value.endsWith('px')) {
+    result.fontSize = Number.parseFloat(value)
+    return true
+  }
+
+  if (selector === 'body') {
+    const body = result.body ||= {}
+    if (prop === 'font-weight' && /^\d+$/.test(value)) {
+      // generated alongside the normal-weight step, not a separate choice
+      body.weight = Number(value)
+      return true
+    }
+    if (prop === 'text-transform' && value === 'uppercase') {
+      body.uppercase = true
+      return true
+    }
+    if (prop === 'font-style' && value === 'italic') {
+      body.italic = true
+      return true
+    }
+    if (prop === 'letter-spacing' && value.endsWith('em')) {
+      body.letterSpacing = Number.parseFloat(value)
+      return true
+    }
+    if (prop === 'line-height' && /^\d+(?:\.\d+)?$/.test(value)) {
+      body.lineHeight = Number(value)
+      return true
+    }
+    return false
+  }
+
+  // The heading rule only carries the serif stack. `var(--font-serif)` is a
+  // no-op (the @theme line already set it); a literal family is an older
+  // export, so it lands on serif and keeps round-tripping.
+  if (selector === 'h1, h2, h3, h4, h5, h6') {
+    if (prop === 'font-family') {
+      if (value.includes('var(--font-serif)')) return true
+      const family = value.match(/^'([^']+)'/) || value.match(/^"([^"]+)"/)
+      if (family) {
+        result.serif ||= family[1]
+        return true
+      }
+    }
+    return false
+  }
+
+  if (selector === ':root') {
+    if (prop === '--ui-radius' && value.endsWith('rem')) {
+      result.radius = Number.parseFloat(value)
+      return true
+    }
+    if (prop === '--ui-primary' && value === 'black') {
+      result.blackAsPrimary = true
+      return true
+    }
+    return false
+  }
+
+  // Only custom properties are theme tokens, a plain declaration must
+  // surface in `skipped`, not ride the token channel into the re-export.
+  if (selector === ':root, .light' || selector === '.light') {
+    if (!prop.startsWith('--')) return false
+    // studio-internal vars never carry theme meaning
+    if (!prop.startsWith('--studio-')) result.light[prop] = value
+    return true
+  }
+  if (selector === '.dark') {
+    if (!prop.startsWith('--')) return false
+    if (!prop.startsWith('--studio-')) result.dark[prop] = value
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Parser for the restricted object-literal grammar generateConfig emits,
+ * a tokenizer, not eval, so pasted content can't execute anything.
+ */
+function parseObjectLiteral(source: string, start: number): { value: any, end: number } {
+  let i = start
+
+  const ws = () => {
+    while (i < source.length && /[\s,]/.test(source[i]!)) i++
+  }
+
+  const parseValue = (): any => {
+    ws()
+    const ch = source[i]
+    if (ch === '{') {
+      i++
+      const obj: Record<string, any> = {}
+      ws()
+      while (source[i] !== '}') {
+        ws()
+        let key: string
+        if (source[i] === '\'' || source[i] === '"') {
+          key = parseString()
+        } else {
+          const match = source.slice(i).match(/^[\w$-]+/)
+          if (!match) throw new Error(`Unexpected character at ${i}`)
+          key = match[0]
+          i += key.length
+        }
+        ws()
+        if (source[i] !== ':') throw new Error(`Expected ':' at ${i}`)
+        i++
+        // Define, not assign: a pasted `__proto__`/`constructor` key must
+        // land as an own property, not walk the setter.
+        Object.defineProperty(obj, key, {
+          value: parseValue(),
+          writable: true,
+          enumerable: true,
+          configurable: true
+        })
+        ws()
+      }
+      i++
+      return obj
+    }
+    if (ch === '[') {
+      i++
+      const array: any[] = []
+      ws()
+      while (source[i] !== ']') {
+        array.push(parseValue())
+        ws()
+      }
+      i++
+      return array
+    }
+    if (ch === '\'' || ch === '"') {
+      return parseString()
+    }
+    const literal = source.slice(i).match(/^(true|false|null|-?\d+(?:\.\d+)?)/)
+    if (literal) {
+      i += literal[0].length
+      if (literal[0] === 'true') return true
+      if (literal[0] === 'false') return false
+      if (literal[0] === 'null') return null
+      return Number(literal[0])
+    }
+    throw new Error(`Unexpected character '${ch}' at ${i}`)
+  }
+
+  const parseString = (): string => {
+    const quote = source[i]!
+    i++
+    let out = ''
+    while (i < source.length && source[i] !== quote) {
+      if (source[i] === '\\') {
+        i++
+        // backslash at EOF, don't append out-of-range source[i] ("undefined")
+        if (i >= source.length) break
+      }
+      out += source[i]
+      i++
+    }
+    i++
+    return out
+  }
+
+  const value = parseValue()
+  return { value, end: i }
+}
+
+function parseConfig(config: string, skipped: string[]): Record<string, any> | undefined {
+  const anchor = config.includes('defineAppConfig(')
+    ? config.indexOf('defineAppConfig(') + 'defineAppConfig('.length
+    : config.includes('ui(') ? config.indexOf('ui(') + 'ui('.length : -1
+  if (anchor === -1) {
+    skipped.push('config: no defineAppConfig(…) or ui(…) call found')
+    return undefined
+  }
+
+  const start = config.indexOf('{', anchor)
+  if (start === -1) return {}
+
+  try {
+    return parseObjectLiteral(config, start).value
+  } catch {
+    skipped.push('config: could not parse the object literal')
+    return undefined
+  }
+}
+
+/** Rebuild `defaults` from per-component defaultVariants, group-wise. */
+function extractDefaults(components: Record<string, any>): StyleOptions['defaults'] {
+  const defaults: { size?: DefaultSize, variants?: Partial<Record<VariantGroup, DefaultVariant>>, colors?: Partial<Record<VariantGroup, DefaultColor>> } = {}
+
+  for (const [group, groupComponents] of Object.entries(VARIANT_GROUPS)) {
+    const colors = groupComponents.map(component => components[component]?.defaultVariants?.color)
+    const candidate = colors.find(Boolean)
+    if (!candidate) continue
+    const consistent = groupComponents.every((component, index) =>
+      COLOR_SUPPORT.includes(component) ? colors[index] === candidate : colors[index] === undefined
+    )
+    if (consistent) {
+      defaults.colors = { ...defaults.colors, [group]: candidate }
+    }
+  }
+
+  const sizes = SIZE_SUPPORT.map(component => components[component]?.defaultVariants?.size)
+  if (sizes[0] && sizes.every(size => size === sizes[0])) {
+    defaults.size = sizes[0]
+  }
+
+  for (const [group, groupComponents] of Object.entries(VARIANT_GROUPS)) {
+    const variants = groupComponents.map(component => components[component]?.defaultVariants?.variant)
+    const candidate = variants.find(Boolean)
+    if (!candidate) continue
+    // Every component that supports the candidate must carry it; ones that
+    // can't express it must carry nothing (that's how the expansion skips).
+    const consistent = groupComponents.every((component, index) =>
+      VARIANT_SUPPORT[component]?.includes(candidate) ? variants[index] === candidate : variants[index] === undefined
+    )
+    if (consistent) {
+      defaults.variants = { ...defaults.variants, [group]: candidate }
+    }
+  }
+
+  // A value carried by every group that could express it is an app-wide
+  // choice, collapsing keeps re-exports byte-identical to the original.
+  const groupValues = new Set(Object.values(defaults.variants || {}))
+  if (groupValues.size === 1) {
+    const [value] = [...groupValues] as [DefaultVariant]
+    const expressible = Object.entries(VARIANT_GROUPS)
+      .filter(([, groupComponents]) => groupComponents.some(component => VARIANT_SUPPORT[component]?.includes(value)))
+      .map(([group]) => group as VariantGroup)
+    if (expressible.every(group => defaults.variants?.[group] === value)) {
+      return { variant: value, ...(defaults.size ? { size: defaults.size } : {}), ...(defaults.colors ? { colors: defaults.colors } : {}) }
+    }
+  }
+
+  return Object.keys(defaults).length ? defaults : undefined
+}
+
+/** Remove the fragments the reconstructed style regenerates, only genuinely explicit overrides remain. */
+function subtractStyleExpansion(components: Record<string, any>, style: StyleOptions): Record<string, any> {
+  const expected = styleComponents(style)
+  const remaining: Record<string, any> = {}
+
+  for (const [name, fragment] of Object.entries(components)) {
+    const expectedFragment = expected[name] || {}
+    const leftover: Record<string, any> = {}
+
+    for (const [slot, classes] of Object.entries((fragment.slots || {}) as Record<string, string>)) {
+      const expectedClasses = expectedFragment.slots?.[slot]
+      if (expectedClasses === classes) continue
+      if (expectedClasses && classes.startsWith(`${expectedClasses} `)) {
+        leftover.slots = { ...leftover.slots, [slot]: classes.slice(expectedClasses.length + 1) }
+      } else {
+        leftover.slots = { ...leftover.slots, [slot]: classes }
+      }
+    }
+
+    const expectedCompounds = [...(expectedFragment.compoundVariants || [])]
+    const compounds = ((fragment.compoundVariants || []) as Array<Record<string, unknown>>).filter((entry) => {
+      const index = expectedCompounds.findIndex(candidate => JSON.stringify(candidate) === JSON.stringify(entry))
+      if (index === -1) return true
+      expectedCompounds.splice(index, 1)
+      return false
+    })
+    if (compounds.length) leftover.compoundVariants = compounds
+
+    const defaultVariants = Object.fromEntries(
+      Object.entries((fragment.defaultVariants || {}) as Record<string, string>)
+        .filter(([key, value]) => expectedFragment.defaultVariants?.[key] !== value)
+    )
+    if (Object.keys(defaultVariants).length) leftover.defaultVariants = defaultVariants
+
+    if (Object.keys(leftover).length) remaining[name] = leftover
+  }
+
+  return remaining
+}
+
+/* -------------------------------------------------------------- entry -- */
+
+export function importTheme(input: { css?: string, config?: string }): ThemeImportResult {
+  const skipped: string[] = []
+  const doc: ThemeDoc = { version: 1 }
+
+  const css = input.css?.trim() ? parseCSS(input.css) : undefined
+  if (css) skipped.push(...css.skipped)
+
+  const parsedConfig = input.config?.trim() ? parseConfig(input.config, skipped) : undefined
+  const ui = parsedConfig?.ui && typeof parsedConfig.ui === 'object' ? parsedConfig.ui : {}
+
+  if (ui.colors && typeof ui.colors === 'object') {
+    const entries = Object.entries(ui.colors as Record<string, unknown>)
+      .filter(([alias, name]) => alias in DEFAULT_COLORS && typeof name === 'string')
+    if (entries.length) doc.colors = Object.fromEntries(entries) as ThemeDoc['colors']
+  }
+
+  if (ui.icons && typeof ui.icons === 'object') {
+    const known = Object.entries(themeIcons).find(([, icons]) => JSON.stringify(icons) === JSON.stringify(ui.icons))
+    if (known) {
+      doc.icons = known[0]
+    } else {
+      skipped.push('config: unrecognized icons object')
+    }
+  }
+
+  const components: Record<string, any> = Object.fromEntries(
+    Object.entries(ui).filter(([key]) => key !== 'colors' && key !== 'icons')
+  )
+
+  // Everything the style axis still owns comes from the config's
+  // `defaultVariants`; the token shades ride the CSS as plain overrides.
+  const style: StyleOptions = {}
+  const defaults = extractDefaults(components)
+  if (defaults) style.defaults = defaults
+
+  const explicit = subtractStyleExpansion(components, style)
+  if (Object.keys(explicit).length) doc.components = explicit
+
+  if (Object.values(style).some(value => value !== undefined)) {
+    doc.style = style
+  }
+
+  if (css) {
+    if (Object.keys(css.palettes).length) {
+      doc.palettes = Object.fromEntries(Object.entries(css.palettes).map(([name, shades]) => [name, { shades }]))
+    }
+    // A body weight without theme steps (older exports) reads as normal.
+    const weights = css.fontWeights || (css.body?.weight !== undefined ? { normal: css.body.weight } : undefined)
+    if (css.font || css.serif || css.mono || weights || css.body) {
+      doc.font = {
+        ...(css.font ? { sans: css.font } : {}),
+        ...(css.serif ? { serif: css.serif } : {}),
+        ...(css.mono ? { mono: css.mono } : {}),
+        ...(weights ? { weights } : {}),
+        ...(css.body?.uppercase ? { uppercase: true } : {}),
+        ...(css.body?.italic ? { italic: true } : {}),
+        ...(css.body?.letterSpacing !== undefined ? { letterSpacing: css.body.letterSpacing } : {}),
+        ...(css.body?.lineHeight !== undefined ? { lineHeight: css.body.lineHeight } : {})
+      }
+    }
+    if (css.fontSize !== undefined) doc.fontSize = css.fontSize
+    if (css.radius !== undefined) doc.radius = css.radius
+    if (css.blackAsPrimary) {
+      doc.blackAsPrimary = true
+      // its .dark counterpart is generated, not a token choice
+      if (css.dark['--ui-primary'] === 'white') delete css.dark['--ui-primary']
+    }
+    // The export restates the library's dark default for light-only
+    // overrides (source-order tie), generated, not a choice; drop it so the
+    // round-trip doesn't grow explicit tokens.
+    for (const [key, value] of Object.entries(css.dark)) {
+      if (key in css.light && value === (LIBRARY_TOKEN_DEFAULTS.dark as Record<string, string>)[key]) {
+        Reflect.deleteProperty(css.dark, key)
+      }
+    }
+    if (Object.keys(css.light).length || Object.keys(css.dark).length) {
+      doc.tokens = {
+        ...(Object.keys(css.light).length ? { light: css.light } : {}),
+        ...(Object.keys(css.dark).length ? { dark: css.dark } : {})
+      }
+    }
+  }
+
+  return { doc, skipped }
+}
diff --git a/docs/app/utils/theme/engine/types.ts b/docs/app/utils/theme/engine/types.ts
new file mode 100644
index 0000000000..da80239d0b
--- /dev/null
+++ b/docs/app/utils/theme/engine/types.ts
@@ -0,0 +1,483 @@
+/**
+ * The theme document: its schema, the tables it expands into, and the
+ * library defaults it is diffed against.
+ *
+ * A theme doc is sparse, so serializing it IS the minimal export. Two style
+ * axes survive on v4, and both map onto public API: default variants/sizes/
+ * colors (`defaultVariants` per component) and semantic token shades
+ * (`--ui-*`). Shadow and border treatments used to live here too, expanded
+ * into static per-component class bundles because the library has no
+ * semantic tokens for them; they come back in v5 on `--ui-shadow-*` /
+ * `--ui-border-width`.
+ */
+import colors from 'tailwindcss/colors'
+
+/* --------------------------------------------------------------- shades -- */
+
+export const SHADES = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950] as const
+
+/**
+ * Every stop any density can emit, a stop stays a valid `Shade` whichever
+ * density produced it.
+ */
+export const SHADES_ALL = [50, 60, 70, 75, 80, 90, 100, 110, 120, 125, 130, 140, 150, 160, 170, 175, 180, 190, 200, 210, 220, 225, 230, 240, 250, 260, 270, 275, 280, 290, 300, 310, 320, 325, 330, 340, 350, 360, 370, 375, 380, 390, 400, 410, 420, 425, 430, 440, 450, 460, 470, 475, 480, 490, 500, 510, 520, 525, 530, 540, 550, 560, 570, 575, 580, 590, 600, 610, 620, 625, 630, 640, 650, 660, 670, 675, 680, 690, 700, 710, 720, 725, 730, 740, 750, 760, 770, 775, 780, 790, 800, 810, 820, 825, 830, 840, 850, 860, 870, 875, 880, 890, 900, 910, 920, 925, 930, 940, 950] as const
+
+export type Shade = typeof SHADES_ALL[number]
+
+/** Stop density as the gap between stops, ordered coarse → fine (detectStopStep relies on the order). */
+export const SHADE_STEPS = [100, 50, 25, 10] as const
+
+export type ShadeStep = typeof SHADE_STEPS[number]
+
+/** The stops each density emits: 11, 19, 37 and 91. */
+export const SHADE_SETS: Record<ShadeStep, readonly Shade[]> = {
+  // 100 is the only irregular set, 50/950 are half-steps at the ends.
+  100: SHADES,
+  50: SHADES_ALL.filter(shade => shade % 50 === 0),
+  25: SHADES_ALL.filter(shade => shade % 25 === 0),
+  10: SHADES_ALL.filter(shade => shade % 10 === 0)
+}
+
+export type ShadeStop = 'white' | Shade | 'black'
+
+/**
+ * The shade sliders' travel: a density's stops plus literal white/black ends,
+ * several stock defaults are literals the ramp can't express (--ui-bg is
+ * `white`).
+ */
+const ladder = (step: ShadeStep): readonly ShadeStop[] => ['white', ...SHADE_SETS[step], 'black']
+
+export const SHADE_LADDERS: Record<ShadeStep, readonly ShadeStop[]> = {
+  100: ladder(100),
+  50: ladder(50),
+  25: ladder(25),
+  10: ladder(10)
+}
+
+/** The standard ladder, what stock ramps (and plain rows) travel. */
+export const SHADE_LADDER = SHADE_LADDERS[100]
+
+export type ColorAlias = 'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'error' | 'neutral'
+
+export interface ThemePalette {
+  shades: Partial<Record<Shade, string>>
+}
+
+/**
+ * A theme is a sparse document, only explicit overrides, everything absent
+ * inherits Nuxt UI defaults, so serializing it *is* the minimal export.
+ */
+export interface ThemeDoc {
+  version: 1
+  /** L0, custom palettes, injected as `--color-{name}-{shade}` */
+  palettes?: Record<string, ThemePalette>
+  /** L1, alias → palette name (tailwind or a key of `palettes`) */
+  colors?: Partial<Record<ColorAlias, string>>
+  blackAsPrimary?: boolean
+  /** L2, semantic `--ui-*` token overrides per mode */
+  tokens?: {
+    light?: Record<string, string>
+    dark?: Record<string, string>
+  }
+  radius?: number
+  /** Root font size in px (`html { font-size }`), scales every rem-based metric */
+  fontSize?: number
+  font?: {
+    sans?: string
+    /**
+     * Tailwind's other two stacks. Setting `mono` is all `font-mono` and the
+     * `code`/`kbd`/`pre`/`samp` elements need, preflight wires them from the
+     * variable. Nothing consumes `--font-serif`, so it doubles as the heading
+     * family through one element rule, until v5 ships `--ui-font-heading`.
+     */
+    serif?: string
+    mono?: string
+    /**
+     * Sparse overrides for tailwind's weight steps (`font-medium` compiles to
+     * `var(--font-weight-medium)`); normal also drives classless body text.
+     */
+    weights?: { normal?: number, medium?: number, semibold?: number, bold?: number }
+    uppercase?: boolean
+    italic?: boolean
+    /** Tracking in em. */
+    letterSpacing?: number
+    /** Unitless line height (browser/tailwind default is 1.5). */
+    lineHeight?: number
+  }
+  icons?: string
+  /** Default variants and semantic token shades. */
+  style?: StyleOptions
+  /** L4, per-component overrides merged into `app.config ui.<component>` */
+  components?: Record<string, Record<string, unknown>>
+}
+
+export const DEFAULT_COLORS: Record<ColorAlias, string> = {
+  primary: 'green',
+  secondary: 'blue',
+  success: 'green',
+  info: 'blue',
+  warning: 'yellow',
+  error: 'red',
+  neutral: 'slate'
+}
+
+/** Every color alias that isn't primary or neutral. */
+export const SEMANTIC_ALIASES = ['secondary', 'success', 'info', 'warning', 'error'] as const
+
+export const THEME_DEFAULTS = {
+  radius: 0.25,
+  fontSize: 16,
+  font: 'Public Sans',
+  icons: 'lucide'
+} as const
+
+/* ---------------------------------------------------------------- style -- */
+
+export type DefaultVariant = 'default' | 'solid' | 'outline' | 'soft' | 'subtle' | 'ghost' | 'link' | 'none'
+export type DefaultSize = 'default' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+export type DefaultColor = 'default' | 'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'error' | 'neutral'
+export type VariantGroup = 'buttons' | 'panels' | 'inputs'
+
+export interface StyleOptions {
+  /**
+   * Default variant/size/color, expanded into per-component `defaultVariants`
+   * only where the component supports the value. `variant` is app-wide;
+   * `variants`/`colors` refine per group and win where set.
+   */
+  defaults?: { variant?: DefaultVariant, size?: DefaultSize, variants?: Partial<Record<VariantGroup, DefaultVariant>>, colors?: Partial<Record<VariantGroup, DefaultColor>> }
+  /**
+   * Semantic token → ramp shade, keys whitelisted in TOKEN_SHADE_TARGETS.
+   * An absent mode stays inherited, presets hydrating one mode must not
+   * leak a phantom override for the other into exports.
+   */
+  tokenShades?: Record<string, { light?: ShadeStop, dark?: ShadeStop }>
+}
+
+/** The whole input family shares input's variant vocabulary (they extend it via defu). */
+const FIELD_VARIANTS = ['outline', 'soft', 'subtle', 'ghost', 'none']
+const FIELD_COMPONENTS = ['input', 'select', 'textarea', 'selectMenu', 'inputMenu', 'inputNumber', 'inputTags', 'inputDate', 'inputTime', 'pinInput']
+
+/** Which components support which default variant values. */
+export const VARIANT_SUPPORT: Record<string, string[]> = {
+  button: ['solid', 'outline', 'soft', 'subtle', 'ghost', 'link'],
+  badge: ['solid', 'outline', 'soft', 'subtle'],
+  alert: ['solid', 'outline', 'soft', 'subtle'],
+  card: ['solid', 'outline', 'soft', 'subtle'],
+  empty: ['solid', 'outline', 'soft', 'subtle'],
+  // fields have no solid variant, an unsupported value would silently unstyle them
+  ...Object.fromEntries(FIELD_COMPONENTS.map(component => [component, FIELD_VARIANTS]))
+}
+
+/**
+ * Components the app-wide Size default scales, exactly the xs–xl axis.
+ * Components on other scales (avatar's 3xs–3xl, kbd's sm–lg) stay out.
+ */
+export const SIZE_SUPPORT = [
+  'button', 'badge', ...FIELD_COMPONENTS, 'inputRating',
+  'tabs', 'checkbox', 'checkboxGroup', 'radioGroup', 'switch', 'slider', 'stepper',
+  'calendar', 'colorPicker', 'fileUpload', 'formField', 'fieldGroup',
+  'dropdownMenu', 'contextMenu', 'commandPalette', 'listbox'
+]
+
+/** Components with a color prop, the panels group has no color axis. */
+export const COLOR_SUPPORT = ['button', 'badge', ...FIELD_COMPONENTS]
+
+/** Component groups behind the per-group default-variant selects. */
+export const VARIANT_GROUPS: Record<VariantGroup, string[]> = {
+  buttons: ['button', 'badge'],
+  panels: ['card', 'alert', 'empty'],
+  inputs: FIELD_COMPONENTS
+}
+
+/** Color scale a token slider walks, neutral, or any semantic alias's ramp. */
+export type TokenRamp = 'neutral' | 'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'error'
+
+export type TokenGroup = 'colors' | 'background' | 'text' | 'border'
+
+export const TOKEN_GROUPS: Array<{ key: TokenGroup, label: string }> = [
+  { key: 'colors', label: 'Color shades' },
+  { key: 'background', label: 'Background shades' },
+  { key: 'text', label: 'Text shades' },
+  { key: 'border', label: 'Border shades' }
+]
+
+/**
+ * Semantic tokens exposed as per-mode shade sliders. `defaults` are the
+ * LIBRARY's real resting values, some are the literal ladder ends (light
+ * --ui-bg is `white`, not a ramp stop); `ramp` names the scale the slider walks.
+ */
+export const TOKEN_SHADE_TARGETS: Array<{ token: string, label: string, ramp: TokenRamp, group: TokenGroup, defaults: { light: ShadeStop, dark: ShadeStop } }> = [
+  { token: '--ui-primary', label: 'Primary', ramp: 'primary', group: 'colors', defaults: { light: 500, dark: 400 } },
+  { token: '--ui-secondary', label: 'Secondary', ramp: 'secondary', group: 'colors', defaults: { light: 500, dark: 400 } },
+  { token: '--ui-success', label: 'Success', ramp: 'success', group: 'colors', defaults: { light: 500, dark: 400 } },
+  { token: '--ui-info', label: 'Info', ramp: 'info', group: 'colors', defaults: { light: 500, dark: 400 } },
+  { token: '--ui-warning', label: 'Warning', ramp: 'warning', group: 'colors', defaults: { light: 500, dark: 400 } },
+  { token: '--ui-error', label: 'Error', ramp: 'error', group: 'colors', defaults: { light: 500, dark: 400 } },
+  { token: '--ui-bg', label: 'Default', ramp: 'neutral', group: 'background', defaults: { light: 'white', dark: 900 } },
+  { token: '--ui-bg-muted', label: 'Muted', ramp: 'neutral', group: 'background', defaults: { light: 50, dark: 800 } },
+  { token: '--ui-bg-elevated', label: 'Elevated', ramp: 'neutral', group: 'background', defaults: { light: 100, dark: 800 } },
+  { token: '--ui-bg-accented', label: 'Accented', ramp: 'neutral', group: 'background', defaults: { light: 200, dark: 700 } },
+  { token: '--ui-bg-inverted', label: 'Inverted', ramp: 'neutral', group: 'background', defaults: { light: 900, dark: 'white' } },
+  { token: '--ui-text-dimmed', label: 'Dimmed', ramp: 'neutral', group: 'text', defaults: { light: 400, dark: 500 } },
+  { token: '--ui-text-muted', label: 'Muted', ramp: 'neutral', group: 'text', defaults: { light: 500, dark: 400 } },
+  { token: '--ui-text-toned', label: 'Toned', ramp: 'neutral', group: 'text', defaults: { light: 600, dark: 300 } },
+  { token: '--ui-text', label: 'Default', ramp: 'neutral', group: 'text', defaults: { light: 700, dark: 200 } },
+  { token: '--ui-text-highlighted', label: 'Highlighted', ramp: 'neutral', group: 'text', defaults: { light: 900, dark: 'white' } },
+  { token: '--ui-text-inverted', label: 'Inverted', ramp: 'neutral', group: 'text', defaults: { light: 'white', dark: 900 } },
+  { token: '--ui-border', label: 'Default', ramp: 'neutral', group: 'border', defaults: { light: 200, dark: 800 } },
+  { token: '--ui-border-muted', label: 'Muted', ramp: 'neutral', group: 'border', defaults: { light: 200, dark: 700 } },
+  { token: '--ui-border-accented', label: 'Accented', ramp: 'neutral', group: 'border', defaults: { light: 300, dark: 700 } },
+  { token: '--ui-border-inverted', label: 'Inverted', ramp: 'neutral', group: 'border', defaults: { light: 900, dark: 'white' } }
+]
+/**
+ * A ramp shade reference, or the literal for white/black. In-between stops
+ * (finer than 100) have no `--ui-color-*` indirection, the runtime colors
+ * plugin only generates the 11 standard stops, so they hit the custom
+ * ramp's `--color-*` directly; such stops only exist on custom palettes,
+ * whose @theme block defines those vars in both preview and export.
+ */
+function shadeRef(ramp: string, stop: ShadeStop | number): string {
+  if (stop === 'white' || stop === 'black') return stop
+  if (typeof stop === 'number' && !(SHADES as readonly number[]).includes(stop)) {
+    return `var(--color-custom-${ramp}-${stop})`
+  }
+  return `var(--ui-color-${ramp}-${stop})`
+}
+
+/** The `ui.<component>` override shape the studio and presets both speak. */
+interface ComponentFragment {
+  slots?: Record<string, string>
+  compoundVariants?: Array<Record<string, unknown>>
+  defaultVariants?: Record<string, string>
+}
+
+type Fragments = Record<string, ComponentFragment>
+
+/** Semantic token shades, the only CSS variables a style still emits. */
+export function styleTokens(style: StyleOptions): { light: Record<string, string>, dark: Record<string, string> } {
+  const light: Record<string, string> = {}
+  const dark: Record<string, string> = {}
+
+  for (const [token, shade] of Object.entries(style.tokenShades || {})) {
+    const target = TOKEN_SHADE_TARGETS.find(target => target.token === token)
+    if (target) {
+      if (shade.light !== undefined) light[token] = shadeRef(target.ramp, shade.light)
+      if (shade.dark !== undefined) dark[token] = shadeRef(target.ramp, shade.dark)
+    }
+  }
+
+  return { light, dark }
+}
+
+/** Expand default variant/size/color choices into `ui.<component>` overrides. */
+export function styleComponents(style: StyleOptions): Fragments {
+  // App-wide defaults, only where the component supports the chosen value.
+  const defaults: Fragments = {}
+  const variant = style.defaults?.variant
+  if (variant && variant !== 'default') {
+    for (const [component, supported] of Object.entries(VARIANT_SUPPORT)) {
+      if (supported.includes(variant)) {
+        defaults[component] = { defaultVariants: { variant } }
+      }
+    }
+  }
+  // group refinements replace the app-wide value for the components they cover
+  for (const [group, components] of Object.entries(VARIANT_GROUPS)) {
+    const groupVariant = style.defaults?.variants?.[group as VariantGroup]
+    if (groupVariant && groupVariant !== 'default') {
+      for (const component of components) {
+        if (VARIANT_SUPPORT[component]?.includes(groupVariant)) {
+          defaults[component] = {
+            ...defaults[component],
+            defaultVariants: { ...defaults[component]?.defaultVariants, variant: groupVariant }
+          }
+        }
+      }
+    }
+  }
+
+  // Per-group default colors, only on components with a color axis.
+  for (const [group, components] of Object.entries(VARIANT_GROUPS)) {
+    const groupColor = style.defaults?.colors?.[group as VariantGroup]
+    if (groupColor && groupColor !== 'default') {
+      for (const component of components) {
+        if (COLOR_SUPPORT.includes(component)) {
+          defaults[component] = {
+            ...defaults[component],
+            defaultVariants: { ...(defaults[component] as any)?.defaultVariants, color: groupColor }
+          }
+        }
+      }
+    }
+  }
+
+  const size = style.defaults?.size
+  if (size && size !== 'default') {
+    for (const component of SIZE_SUPPORT) {
+      defaults[component] = {
+        ...defaults[component],
+        defaultVariants: { ...(defaults[component] as any)?.defaultVariants, size }
+      }
+    }
+  }
+
+  return defaults
+}
+
+/**
+ * Merge two `ui.<component>` override fragments so both take effect: slot
+ * class strings concatenate (extra last, winning the tailwind-merge),
+ * compoundVariants append in the same order. A spread would silently drop
+ * whichever side loses.
+ */
+export function mergeComponentOverrides(
+  base: Record<string, any> | undefined,
+  extra: Record<string, any> | undefined
+): Record<string, any> | undefined {
+  if (!base || !Object.keys(base).length) return extra
+  if (!extra || !Object.keys(extra).length) return base
+
+  const result: Record<string, any> = {}
+  for (const key of new Set([...Object.keys(base), ...Object.keys(extra)])) {
+    const a = base[key]
+    const b = extra[key]
+    if (a === undefined) {
+      result[key] = b
+    } else if (b === undefined) {
+      result[key] = a
+    } else if (key === 'compoundVariants' && Array.isArray(a) && Array.isArray(b)) {
+      result[key] = [...a, ...b]
+    } else if (key === 'defaultVariants') {
+      // variant NAMES, not class strings, later value replaces per key
+      result[key] = { ...a, ...b }
+    } else if (typeof a === 'string' && typeof b === 'string') {
+      result[key] = `${a} ${b}`
+    } else if (typeof a === 'object' && typeof b === 'object' && !Array.isArray(a) && !Array.isArray(b)) {
+      result[key] = mergeComponentOverrides(a, b)
+    } else {
+      result[key] = b
+    }
+  }
+  return result
+}
+
+/** Merge two whole `ui` records component-wise. */
+export function mergeUi(
+  base: Record<string, any> | undefined,
+  extra: Record<string, any> | undefined
+): Record<string, any> {
+  const result: Record<string, any> = {}
+  for (const key of new Set([...Object.keys(base || {}), ...Object.keys(extra || {})])) {
+    const merged = mergeComponentOverrides(base?.[key], extra?.[key])
+    if (merged && Object.keys(merged).length) result[key] = merged
+  }
+  return result
+}
+
+/** Nothing set that changes rendering. */
+export function isDefaultStyle(style: StyleOptions = {}): boolean {
+  return !Object.values(style).some(value => value && value !== 'default')
+}
+
+/* ------------------------------------------------------ library defaults -- */
+
+/**
+ * The semantic token defaults as @nuxt/ui ships them (src/runtime/index.css).
+ * Exports diff against THESE, not the docs site's diverging baseline, an
+ * exported theme must reproduce the preview on a stock library install.
+ */
+export const LIBRARY_TOKEN_DEFAULTS = {
+  light: {
+    // the --ui-<alias> tokens are generated by the runtime colors plugin, not index.css
+    '--ui-primary': 'var(--ui-color-primary-500)',
+    '--ui-secondary': 'var(--ui-color-secondary-500)',
+    '--ui-success': 'var(--ui-color-success-500)',
+    '--ui-info': 'var(--ui-color-info-500)',
+    '--ui-warning': 'var(--ui-color-warning-500)',
+    '--ui-error': 'var(--ui-color-error-500)',
+    '--ui-text-dimmed': 'var(--ui-color-neutral-400)',
+    '--ui-text-muted': 'var(--ui-color-neutral-500)',
+    '--ui-text-toned': 'var(--ui-color-neutral-600)',
+    '--ui-text': 'var(--ui-color-neutral-700)',
+    '--ui-text-highlighted': 'var(--ui-color-neutral-900)',
+    '--ui-text-inverted': 'white',
+    '--ui-bg': 'white',
+    '--ui-bg-muted': 'var(--ui-color-neutral-50)',
+    '--ui-bg-elevated': 'var(--ui-color-neutral-100)',
+    '--ui-bg-accented': 'var(--ui-color-neutral-200)',
+    '--ui-bg-inverted': 'var(--ui-color-neutral-900)',
+    '--ui-border': 'var(--ui-color-neutral-200)',
+    '--ui-border-muted': 'var(--ui-color-neutral-200)',
+    '--ui-border-accented': 'var(--ui-color-neutral-300)',
+    '--ui-border-inverted': 'var(--ui-color-neutral-900)'
+  },
+  dark: {
+    '--ui-primary': 'var(--ui-color-primary-400)',
+    '--ui-secondary': 'var(--ui-color-secondary-400)',
+    '--ui-success': 'var(--ui-color-success-400)',
+    '--ui-info': 'var(--ui-color-info-400)',
+    '--ui-warning': 'var(--ui-color-warning-400)',
+    '--ui-error': 'var(--ui-color-error-400)',
+    '--ui-text-dimmed': 'var(--ui-color-neutral-500)',
+    '--ui-text-muted': 'var(--ui-color-neutral-400)',
+    '--ui-text-toned': 'var(--ui-color-neutral-300)',
+    '--ui-text': 'var(--ui-color-neutral-200)',
+    '--ui-text-highlighted': 'white',
+    '--ui-text-inverted': 'var(--ui-color-neutral-900)',
+    '--ui-bg': 'var(--ui-color-neutral-900)',
+    '--ui-bg-muted': 'var(--ui-color-neutral-800)',
+    '--ui-bg-elevated': 'var(--ui-color-neutral-800)',
+    '--ui-bg-accented': 'var(--ui-color-neutral-700)',
+    '--ui-bg-inverted': 'white',
+    '--ui-border': 'var(--ui-color-neutral-800)',
+    '--ui-border-muted': 'var(--ui-color-neutral-700)',
+    '--ui-border-accented': 'var(--ui-color-neutral-700)',
+    '--ui-border-inverted': 'white'
+  }
+} as const
+
+// Standard stops ride the `--ui-color-<alias>-<shade>` indirection; midpoints
+// have none (the runtime colours plugin only generates the 11 standard stops)
+// so they emit against `--color-custom-<alias>-<stop>` instead. One
+// alternation parses both forms with the ramp in the same capture position.
+const UI_COLOR_RE = /^var\(--(?:ui-color|color-custom)-([a-z]+)-(\d{2,3})\)$/
+
+/**
+ * Parse a shade reference the studio emits (either form) to `{ alias, shade }`.
+ * Callers apply their own ownership check, a foreign-ramp ref is parsed but
+ * not adopted.
+ */
+export function parseUiColorRef(value?: string): { alias: string, shade: number } | undefined {
+  const match = value?.match(UI_COLOR_RE)
+  return match ? { alias: match[1]!, shade: Number(match[2]) } : undefined
+}
+
+export function resolveAlias(doc: ThemeDoc, alias: ColorAlias): string {
+  return doc.colors?.[alias] || DEFAULT_COLORS[alias]
+}
+
+/** Color of a palette shade: custom palette first, then its base, then tailwind. */
+export function resolveShade(doc: ThemeDoc, palette: string, shade: Shade): string | undefined {
+  const custom = doc.palettes?.[palette]
+  if (custom) {
+    return custom.shades[shade]
+  }
+  const tailwind = (colors as Record<string, unknown>)[palette]
+  if (tailwind && typeof tailwind === 'object') {
+    return (tailwind as Record<string, string>)[shade]
+  }
+  return undefined
+}
+
+/* -------------------------------------------------------------- defaults -- */
+
+/** A document with no overrides means "stock Nuxt UI". */
+export function isDefaultTheme(doc: ThemeDoc): boolean {
+  return !doc.palettes && !doc.colors && !doc.blackAsPrimary && !doc.tokens
+    && doc.radius === undefined && doc.fontSize === undefined
+    && !doc.font?.sans && !doc.font?.serif && !doc.font?.mono && !doc.font?.weights
+    && !doc.font?.uppercase && !doc.font?.italic
+    && doc.font?.letterSpacing === undefined && doc.font?.lineHeight === undefined
+    && !doc.icons && !doc.components
+    && isDefaultStyle(doc.style)
+}
diff --git a/docs/app/utils/theme/icons.ts b/docs/app/utils/theme/icons.ts
new file mode 100644
index 0000000000..0445e2e789
--- /dev/null
+++ b/docs/app/utils/theme/icons.ts
@@ -0,0 +1,562 @@
+import lucide from '../../../../src/theme/icons'
+
+// Picking a set replaces appConfig.ui.icons wholesale, so every set must
+// map the full key list from src/theme/icons, a missing key would blank
+// that icon across the whole app. Names are validated against the Iconify
+// API (sets beyond lucide resolve through @nuxt/icon's API fallback).
+export const themeIcons = {
+  lucide,
+  bootstrap: {
+    arrowDown: 'i-bi-arrow-down',
+    arrowLeft: 'i-bi-arrow-left',
+    arrowRight: 'i-bi-arrow-right',
+    arrowUp: 'i-bi-arrow-up',
+    caution: 'i-bi-exclamation-circle',
+    check: 'i-bi-check',
+    chevronDoubleLeft: 'i-bi-chevron-double-left',
+    chevronDoubleRight: 'i-bi-chevron-double-right',
+    chevronDown: 'i-bi-chevron-down',
+    chevronLeft: 'i-bi-chevron-left',
+    chevronRight: 'i-bi-chevron-right',
+    chevronUp: 'i-bi-chevron-up',
+    close: 'i-bi-x',
+    copy: 'i-bi-clipboard',
+    copyCheck: 'i-bi-clipboard-check',
+    dark: 'i-bi-moon',
+    drag: 'i-bi-grip-vertical',
+    ellipsis: 'i-bi-three-dots',
+    error: 'i-bi-x-circle',
+    external: 'i-bi-box-arrow-up-right',
+    eye: 'i-bi-eye',
+    eyeOff: 'i-bi-eye-slash',
+    file: 'i-bi-file-earmark',
+    folder: 'i-bi-folder',
+    folderOpen: 'i-bi-folder2-open',
+    hash: 'i-bi-hash',
+    info: 'i-bi-info-circle',
+    light: 'i-bi-sun',
+    loading: 'i-bi-arrow-repeat',
+    menu: 'i-bi-list',
+    minus: 'i-bi-dash',
+    panelClose: 'i-bi-arrow-bar-left',
+    panelOpen: 'i-bi-arrow-bar-right',
+    plus: 'i-bi-plus',
+    reload: 'i-bi-arrow-counterclockwise',
+    search: 'i-bi-search',
+    stop: 'i-bi-square',
+    star: 'i-bi-star',
+    success: 'i-bi-check-circle',
+    system: 'i-bi-display',
+    tip: 'i-bi-lightbulb',
+    upload: 'i-bi-upload',
+    warning: 'i-bi-exclamation-triangle'
+  },
+  heroicons: {
+    arrowDown: 'i-heroicons-arrow-down',
+    arrowLeft: 'i-heroicons-arrow-left',
+    arrowRight: 'i-heroicons-arrow-right',
+    arrowUp: 'i-heroicons-arrow-up',
+    caution: 'i-heroicons-exclamation-circle',
+    check: 'i-heroicons-check',
+    chevronDoubleLeft: 'i-heroicons-chevron-double-left',
+    chevronDoubleRight: 'i-heroicons-chevron-double-right',
+    chevronDown: 'i-heroicons-chevron-down',
+    chevronLeft: 'i-heroicons-chevron-left',
+    chevronRight: 'i-heroicons-chevron-right',
+    chevronUp: 'i-heroicons-chevron-up',
+    close: 'i-heroicons-x-mark',
+    copy: 'i-heroicons-clipboard',
+    copyCheck: 'i-heroicons-clipboard-document-check',
+    dark: 'i-heroicons-moon',
+    drag: 'i-heroicons-bars-3',
+    ellipsis: 'i-heroicons-ellipsis-horizontal',
+    error: 'i-heroicons-x-circle',
+    external: 'i-heroicons-arrow-up-right',
+    eye: 'i-heroicons-eye',
+    eyeOff: 'i-heroicons-eye-slash',
+    file: 'i-heroicons-document',
+    folder: 'i-heroicons-folder',
+    folderOpen: 'i-heroicons-folder-open',
+    hash: 'i-heroicons-hashtag',
+    info: 'i-heroicons-information-circle',
+    light: 'i-heroicons-sun',
+    loading: 'i-heroicons-arrow-path',
+    menu: 'i-heroicons-bars-3',
+    minus: 'i-heroicons-minus',
+    panelClose: 'i-heroicons-chevron-left',
+    panelOpen: 'i-heroicons-chevron-right',
+    plus: 'i-heroicons-plus',
+    reload: 'i-heroicons-arrow-uturn-left',
+    search: 'i-heroicons-magnifying-glass',
+    stop: 'i-heroicons-stop',
+    star: 'i-heroicons-star',
+    success: 'i-heroicons-check-circle',
+    system: 'i-heroicons-computer-desktop',
+    tip: 'i-heroicons-light-bulb',
+    upload: 'i-heroicons-arrow-up-tray',
+    warning: 'i-heroicons-exclamation-triangle'
+  },
+  iconoir: {
+    arrowDown: 'i-iconoir-arrow-down',
+    arrowLeft: 'i-iconoir-arrow-left',
+    arrowRight: 'i-iconoir-arrow-right',
+    arrowUp: 'i-iconoir-arrow-up',
+    caution: 'i-iconoir-warning-circle',
+    check: 'i-iconoir-check',
+    chevronDoubleLeft: 'i-iconoir-fast-arrow-left',
+    chevronDoubleRight: 'i-iconoir-fast-arrow-right',
+    chevronDown: 'i-iconoir-nav-arrow-down',
+    chevronLeft: 'i-iconoir-nav-arrow-left',
+    chevronRight: 'i-iconoir-nav-arrow-right',
+    chevronUp: 'i-iconoir-nav-arrow-up',
+    close: 'i-iconoir-xmark',
+    copy: 'i-iconoir-copy',
+    copyCheck: 'i-iconoir-clipboard-check',
+    dark: 'i-iconoir-half-moon',
+    drag: 'i-iconoir-menu',
+    ellipsis: 'i-iconoir-more-horiz',
+    error: 'i-iconoir-xmark-circle',
+    external: 'i-iconoir-arrow-up-right',
+    eye: 'i-iconoir-eye',
+    eyeOff: 'i-iconoir-eye-closed',
+    file: 'i-iconoir-page',
+    folder: 'i-iconoir-folder',
+    // iconoir has no open-folder glyph, repeat the closed folder rather
+    // than show a book on expanded tree nodes
+    folderOpen: 'i-iconoir-folder',
+    hash: 'i-iconoir-hashtag',
+    info: 'i-iconoir-info-circle',
+    light: 'i-iconoir-sun-light',
+    loading: 'i-iconoir-refresh',
+    menu: 'i-iconoir-menu',
+    minus: 'i-iconoir-minus',
+    panelClose: 'i-iconoir-sidebar-collapse',
+    panelOpen: 'i-iconoir-sidebar-expand',
+    plus: 'i-iconoir-plus',
+    reload: 'i-iconoir-undo',
+    search: 'i-iconoir-search',
+    stop: 'i-iconoir-square',
+    star: 'i-iconoir-star',
+    success: 'i-iconoir-check-circle',
+    system: 'i-iconoir-computer',
+    tip: 'i-iconoir-light-bulb',
+    upload: 'i-iconoir-upload',
+    warning: 'i-iconoir-warning-triangle'
+  },
+  material: {
+    arrowDown: 'i-material-symbols-arrow-downward-rounded',
+    arrowLeft: 'i-material-symbols-arrow-back-rounded',
+    arrowRight: 'i-material-symbols-arrow-forward-rounded',
+    arrowUp: 'i-material-symbols-arrow-upward-rounded',
+    caution: 'i-material-symbols-error-outline-rounded',
+    check: 'i-material-symbols-check-rounded',
+    chevronDoubleLeft: 'i-material-symbols-keyboard-double-arrow-left-rounded',
+    chevronDoubleRight: 'i-material-symbols-keyboard-double-arrow-right-rounded',
+    chevronDown: 'i-material-symbols-keyboard-arrow-down-rounded',
+    chevronLeft: 'i-material-symbols-chevron-left-rounded',
+    chevronRight: 'i-material-symbols-chevron-right-rounded',
+    chevronUp: 'i-material-symbols-keyboard-arrow-up-rounded',
+    close: 'i-material-symbols-close-rounded',
+    copy: 'i-material-symbols-content-copy-outline-rounded',
+    copyCheck: 'i-material-symbols-inventory-rounded',
+    dark: 'i-material-symbols-dark-mode-outline-rounded',
+    drag: 'i-material-symbols-drag-indicator',
+    ellipsis: 'i-material-symbols-more-horiz',
+    error: 'i-material-symbols-cancel-outline-rounded',
+    external: 'i-material-symbols-arrow-outward-rounded',
+    eye: 'i-material-symbols-visibility-outline-rounded',
+    eyeOff: 'i-material-symbols-visibility-off-outline-rounded',
+    file: 'i-material-symbols-description-outline-rounded',
+    folder: 'i-material-symbols-folder-outline-rounded',
+    folderOpen: 'i-material-symbols-folder-open-outline-rounded',
+    hash: 'i-material-symbols-tag-rounded',
+    info: 'i-material-symbols-info-outline-rounded',
+    // colon form: the dashed name would resolve against the separate
+    // material-symbols-light collection and never load
+    light: 'i-material-symbols:light-mode-outline-rounded',
+    loading: 'i-material-symbols-progress-activity',
+    menu: 'i-material-symbols-menu-rounded',
+    minus: 'i-material-symbols-remove-rounded',
+    panelClose: 'i-material-symbols-left-panel-close-outline-rounded',
+    panelOpen: 'i-material-symbols-left-panel-open-outline-rounded',
+    plus: 'i-material-symbols-add-rounded',
+    reload: 'i-material-symbols-refresh-rounded',
+    search: 'i-material-symbols-search-rounded',
+    stop: 'i-material-symbols-stop-outline-rounded',
+    star: 'i-material-symbols-star-outline-rounded',
+    success: 'i-material-symbols-check-circle-outline-rounded',
+    system: 'i-material-symbols-desktop-windows-outline-rounded',
+    tip: 'i-material-symbols-lightbulb-outline-rounded',
+    upload: 'i-material-symbols-upload-rounded',
+    warning: 'i-material-symbols-warning-outline-rounded'
+  },
+  phosphor: {
+    arrowDown: 'i-ph-arrow-down',
+    arrowLeft: 'i-ph-arrow-left',
+    arrowRight: 'i-ph-arrow-right',
+    arrowUp: 'i-ph-arrow-up',
+    caution: 'i-ph-warning-circle',
+    check: 'i-ph-check',
+    chevronDoubleLeft: 'i-ph-caret-double-left',
+    chevronDoubleRight: 'i-ph-caret-double-right',
+    chevronDown: 'i-ph-caret-down',
+    chevronLeft: 'i-ph-caret-left',
+    chevronRight: 'i-ph-caret-right',
+    chevronUp: 'i-ph-caret-up',
+    close: 'i-ph-x',
+    copy: 'i-ph-copy',
+    copyCheck: 'i-ph-check-circle',
+    dark: 'i-ph-moon',
+    drag: 'i-ph-dots-six-vertical',
+    ellipsis: 'i-ph-dots-three',
+    error: 'i-ph-x-circle',
+    external: 'i-ph-arrow-up-right',
+    eye: 'i-ph-eye',
+    eyeOff: 'i-ph-eye-slash',
+    file: 'i-ph-file',
+    folder: 'i-ph-folder',
+    folderOpen: 'i-ph-folder-open',
+    hash: 'i-ph-hash',
+    info: 'i-ph-info',
+    light: 'i-ph-sun',
+    loading: 'i-ph-circle-notch',
+    menu: 'i-ph-list',
+    minus: 'i-ph-minus',
+    panelClose: 'i-ph-caret-left',
+    panelOpen: 'i-ph-caret-right',
+    plus: 'i-ph-plus',
+    reload: 'i-ph-arrow-counter-clockwise',
+    search: 'i-ph-magnifying-glass',
+    stop: 'i-ph-square',
+    star: 'i-ph-star',
+    success: 'i-ph-check-circle',
+    system: 'i-ph-monitor',
+    tip: 'i-ph-lightbulb',
+    upload: 'i-ph-upload',
+    warning: 'i-ph-warning'
+  },
+  remix: {
+    arrowDown: 'i-ri-arrow-down-line',
+    arrowLeft: 'i-ri-arrow-left-line',
+    arrowRight: 'i-ri-arrow-right-line',
+    arrowUp: 'i-ri-arrow-up-line',
+    caution: 'i-ri-error-warning-line',
+    check: 'i-ri-check-line',
+    chevronDoubleLeft: 'i-ri-arrow-left-double-line',
+    chevronDoubleRight: 'i-ri-arrow-right-double-line',
+    chevronDown: 'i-ri-arrow-down-s-line',
+    chevronLeft: 'i-ri-arrow-left-s-line',
+    chevronRight: 'i-ri-arrow-right-s-line',
+    chevronUp: 'i-ri-arrow-up-s-line',
+    close: 'i-ri-close-line',
+    copy: 'i-ri-file-copy-line',
+    copyCheck: 'i-ri-checkbox-multiple-line',
+    dark: 'i-ri-moon-line',
+    drag: 'i-ri-draggable',
+    ellipsis: 'i-ri-more-line',
+    error: 'i-ri-close-circle-line',
+    external: 'i-ri-external-link-line',
+    eye: 'i-ri-eye-line',
+    eyeOff: 'i-ri-eye-off-line',
+    file: 'i-ri-file-line',
+    folder: 'i-ri-folder-line',
+    folderOpen: 'i-ri-folder-open-line',
+    hash: 'i-ri-hashtag',
+    info: 'i-ri-information-line',
+    light: 'i-ri-sun-line',
+    loading: 'i-ri-loader-4-line',
+    menu: 'i-ri-menu-line',
+    minus: 'i-ri-subtract-line',
+    panelClose: 'i-ri-sidebar-fold-line',
+    panelOpen: 'i-ri-sidebar-unfold-line',
+    plus: 'i-ri-add-line',
+    reload: 'i-ri-arrow-go-back-line',
+    search: 'i-ri-search-line',
+    stop: 'i-ri-stop-line',
+    star: 'i-ri-star-line',
+    success: 'i-ri-checkbox-circle-line',
+    system: 'i-ri-computer-line',
+    tip: 'i-ri-lightbulb-line',
+    upload: 'i-ri-upload-2-line',
+    warning: 'i-ri-alert-line'
+  },
+  tabler: {
+    arrowDown: 'i-tabler-arrow-down',
+    arrowLeft: 'i-tabler-arrow-left',
+    arrowRight: 'i-tabler-arrow-right',
+    arrowUp: 'i-tabler-arrow-up',
+    caution: 'i-tabler-alert-square-rounded',
+    check: 'i-tabler-check',
+    chevronDoubleLeft: 'i-tabler-chevrons-left',
+    chevronDoubleRight: 'i-tabler-chevrons-right',
+    chevronDown: 'i-tabler-chevron-down',
+    chevronLeft: 'i-tabler-chevron-left',
+    chevronRight: 'i-tabler-chevron-right',
+    chevronUp: 'i-tabler-chevron-up',
+    close: 'i-tabler-x',
+    copy: 'i-tabler-copy',
+    copyCheck: 'i-tabler-copy-check',
+    dark: 'i-tabler-moon',
+    drag: 'i-tabler-grip-vertical',
+    ellipsis: 'i-tabler-dots',
+    error: 'i-tabler-square-rounded-x',
+    external: 'i-tabler-external-link',
+    eye: 'i-tabler-eye',
+    eyeOff: 'i-tabler-eye-off',
+    file: 'i-tabler-file',
+    folder: 'i-tabler-folder',
+    folderOpen: 'i-tabler-folder-open',
+    hash: 'i-tabler-hash',
+    info: 'i-tabler-info-square-rounded',
+    light: 'i-tabler-sun',
+    loading: 'i-tabler-loader-2',
+    menu: 'i-tabler-menu',
+    minus: 'i-tabler-minus',
+    panelClose: 'i-tabler-layout-sidebar-left-collapse',
+    panelOpen: 'i-tabler-layout-sidebar-left-expand',
+    plus: 'i-tabler-plus',
+    reload: 'i-tabler-reload',
+    search: 'i-tabler-search',
+    stop: 'i-tabler-player-stop',
+    star: 'i-tabler-star',
+    success: 'i-tabler-square-rounded-check',
+    system: 'i-tabler-device-desktop',
+    tip: 'i-tabler-bulb',
+    upload: 'i-tabler-upload',
+    warning: 'i-tabler-alert-triangle'
+  },
+  // 8-bit pixel-art set for the Comic preset. Pixelarticons is a functional
+  // UI pack (unlike streamline-pixel, which has no arrows/chevrons), but it
+  // still lacks a few glyphs, noted inline where a substitute stands in.
+  pixelarticons: {
+    arrowDown: 'i-pixelarticons-arrow-down',
+    arrowLeft: 'i-pixelarticons-arrow-left',
+    arrowRight: 'i-pixelarticons-arrow-right',
+    arrowUp: 'i-pixelarticons-arrow-up',
+    caution: 'i-pixelarticons-square-alert',
+    check: 'i-pixelarticons-check',
+    // No double-chevron glyph, single directional chevrons keep prev/next
+    // (pagination first/last, calendar year nav) pointing the right way.
+    chevronDoubleLeft: 'i-pixelarticons-chevron-left',
+    chevronDoubleRight: 'i-pixelarticons-chevron-right',
+    chevronDown: 'i-pixelarticons-chevron-down',
+    chevronLeft: 'i-pixelarticons-chevron-left',
+    chevronRight: 'i-pixelarticons-chevron-right',
+    chevronUp: 'i-pixelarticons-chevron-up',
+    close: 'i-pixelarticons-close',
+    copy: 'i-pixelarticons-clipboard',
+    copyCheck: 'i-pixelarticons-clipboard-note',
+    dark: 'i-pixelarticons-moon',
+    // No grip/drag handle, vertical dots read as a draggable affordance.
+    drag: 'i-pixelarticons-more-vertical',
+    ellipsis: 'i-pixelarticons-more-horizontal',
+    error: 'i-pixelarticons-letter-x-circle',
+    external: 'i-pixelarticons-external-link',
+    eye: 'i-pixelarticons-eye',
+    eyeOff: 'i-pixelarticons-eye-off',
+    file: 'i-pixelarticons-file',
+    // No open-folder glyph, repeat the closed folder (as iconoir does).
+    folder: 'i-pixelarticons-folder',
+    folderOpen: 'i-pixelarticons-folder',
+    hash: 'i-pixelarticons-hash',
+    info: 'i-pixelarticons-info-box',
+    light: 'i-pixelarticons-sun',
+    loading: 'i-pixelarticons-loader',
+    menu: 'i-pixelarticons-menu',
+    minus: 'i-pixelarticons-minus',
+    panelClose: 'i-pixelarticons-chevron-left',
+    panelOpen: 'i-pixelarticons-chevron-right',
+    plus: 'i-pixelarticons-plus',
+    reload: 'i-pixelarticons-reload',
+    search: 'i-pixelarticons-search',
+    // No dedicated stop glyph, a filled square is the universal stop mark.
+    stop: 'i-pixelarticons-square',
+    star: 'i-pixelarticons-star',
+    success: 'i-pixelarticons-check',
+    system: 'i-pixelarticons-monitor',
+    tip: 'i-pixelarticons-lightbulb',
+    upload: 'i-pixelarticons-upload',
+    warning: 'i-pixelarticons-warning-diamond'
+  }
+}
+
+export type ThemeIcons = keyof typeof themeIcons
+
+/**
+ * A short strip of a set's own glyphs, for previewing it in a picker row,
+ * these eight differ enough between packs to tell them apart at a glance.
+ */
+export function iconSetSamples(setName: string): string[] {
+  const set = (themeIcons as Record<string, Record<string, string>>)[setName] || {}
+  return ['search', 'check', 'warning', 'light', 'dark', 'star', 'folder', 'upload']
+    .map(key => set[key])
+    .filter((name): name is string => !!name)
+}
+
+/**
+ * Glyphs for the studio's own chrome (toolbar controls, the header Ask-AI
+ * button, the theme-picker/preset button), per icon pack, so the chrome skins
+ * to match the applied theme. Kept OUT of `themeIcons` on purpose: these are
+ * studio-only and must never ride the export's icon config. `reset` is its own
+ * circular-arrow glyph rather than reusing the `reload` semantic key, in
+ * several packs `reload` is a back-arrow that would collide with `undo`.
+ * Import and the group-picker chevron reuse the standard `upload`/`chevronDown`
+ * keys (present in every pack), so they aren't repeated here.
+ */
+export const studioIcons: Record<ThemeIcons, {
+  undo: string
+  redo: string
+  reset: string
+  export: string
+  /** Header "Ask AI" button. */
+  assistant: string
+  /** Theme-picker + preset-menu button. */
+  themes: string
+  /** The studio toolbar's Options panel trigger. */
+  options: string
+  /** The studio toolbar's Text panel trigger. */
+  text: string
+  /** The studio toolbar's Radius trigger. */
+  radius: string
+  /** Preset-menu randomize die. Packs without a die use their shuffle glyph. */
+  dice: string
+}> = {
+  lucide: { undo: 'i-lucide-undo-2', redo: 'i-lucide-redo-2', reset: 'i-lucide-rotate-ccw', export: 'i-lucide-download', assistant: 'i-lucide-bot-message-square', themes: 'i-lucide-swatch-book', options: 'i-lucide-sliders-horizontal', text: 'i-lucide-type', radius: 'i-lucide-square-round-corner', dice: 'i-lucide-dices' },
+  bootstrap: { undo: 'i-bi-arrow-90deg-left', redo: 'i-bi-arrow-90deg-right', reset: 'i-bi-arrow-counterclockwise', export: 'i-bi-download', assistant: 'i-bi-robot', themes: 'i-bi-palette', options: 'i-bi-sliders', text: 'i-bi-fonts', radius: 'i-bi-bounding-box', dice: 'i-bi-dice-5' },
+  heroicons: { undo: 'i-heroicons-arrow-uturn-left', redo: 'i-heroicons-arrow-uturn-right', reset: 'i-heroicons-arrow-path', export: 'i-heroicons-arrow-down-tray', assistant: 'i-heroicons-sparkles', themes: 'i-heroicons-swatch', options: 'i-heroicons-adjustments-horizontal', text: 'i-heroicons-language', radius: 'i-heroicons-stop', dice: 'i-heroicons-arrows-right-left' },
+  iconoir: { undo: 'i-iconoir-undo', redo: 'i-iconoir-redo', reset: 'i-iconoir-refresh-double', export: 'i-iconoir-download', assistant: 'i-iconoir-magic-wand', themes: 'i-iconoir-palette', options: 'i-iconoir-settings', text: 'i-iconoir-text', radius: 'i-iconoir-square', dice: 'i-iconoir-shuffle' },
+  material: { undo: 'i-material-symbols-undo', redo: 'i-material-symbols-redo', reset: 'i-material-symbols-refresh', export: 'i-material-symbols-download', assistant: 'i-material-symbols-robot', themes: 'i-material-symbols-palette', options: 'i-material-symbols-tune', text: 'i-material-symbols-text-fields', radius: 'i-material-symbols-rounded-corner', dice: 'i-material-symbols-shuffle' },
+  phosphor: { undo: 'i-ph-arrow-arc-left', redo: 'i-ph-arrow-arc-right', reset: 'i-ph-arrow-counter-clockwise', export: 'i-ph-download', assistant: 'i-ph-robot', themes: 'i-ph-palette', options: 'i-ph-sliders-horizontal', text: 'i-ph-text-aa', radius: 'i-ph-square', dice: 'i-ph-shuffle' },
+  remix: { undo: 'i-ri-arrow-go-back-line', redo: 'i-ri-arrow-go-forward-line', reset: 'i-ri-restart-line', export: 'i-ri-download-line', assistant: 'i-ri-robot-2-line', themes: 'i-ri-palette-line', options: 'i-ri-equalizer-line', text: 'i-ri-font-size', radius: 'i-ri-rounded-corner', dice: 'i-ri-dice-line' },
+  tabler: { undo: 'i-tabler-arrow-back-up', redo: 'i-tabler-arrow-forward-up', reset: 'i-tabler-refresh', export: 'i-tabler-download', assistant: 'i-tabler-robot', themes: 'i-tabler-palette', options: 'i-tabler-adjustments-horizontal', text: 'i-tabler-typography', radius: 'i-tabler-border-radius', dice: 'i-tabler-dice' },
+  // Pixel pack has no `themes`/`palette` glyph, so `colors-swatch` stands in
+  // for the swatch-book.
+  pixelarticons: { undo: 'i-pixelarticons-undo', redo: 'i-pixelarticons-redo', reset: 'i-pixelarticons-reload', export: 'i-pixelarticons-download', assistant: 'i-pixelarticons-robot', themes: 'i-pixelarticons-colors-swatch', options: 'i-pixelarticons-sliders', text: 'i-pixelarticons-text-add', radius: 'i-pixelarticons-card', dice: 'i-pixelarticons-dice' }
+}
+
+/**
+ * Functional icons the preview demos use beyond the 43 semantic keys (dashboard
+ * nav, account menus, etc.). These are NOT part of any theme, they only skin
+ * the studio's demo content to the applied pack, so they stay out of themeIcons
+ * (and exports). The Lucide names ARE the defaults each demo already hardcodes;
+ * `studioExtraOverrides` supplies a pack's glyph where it differs, falling back
+ * to the Lucide default for any pack/key with no entry.
+ */
+export const STUDIO_EXTRA_DEFAULTS = {
+  bell: 'i-lucide-bell',
+  calendar: 'i-lucide-calendar',
+  settings: 'i-lucide-settings',
+  home: 'i-lucide-house',
+  inbox: 'i-lucide-inbox',
+  logout: 'i-lucide-log-out',
+  trash: 'i-lucide-trash',
+  user: 'i-lucide-user',
+  users: 'i-lucide-users',
+  userPlus: 'i-lucide-user-plus',
+  send: 'i-lucide-send',
+  reply: 'i-lucide-reply',
+  paperclip: 'i-lucide-paperclip',
+  messageCircle: 'i-lucide-message-circle',
+  creditCard: 'i-lucide-credit-card',
+  dollar: 'i-lucide-circle-dollar-sign',
+  cart: 'i-lucide-shopping-cart',
+  chart: 'i-lucide-chart-pie',
+  list: 'i-lucide-list',
+  sort: 'i-lucide-chevrons-up-down',
+  mail: 'i-lucide-mail',
+  heart: 'i-lucide-heart',
+  github: 'i-lucide-github',
+  trendingUp: 'i-lucide-trending-up',
+  trendingDown: 'i-lucide-trending-down',
+  tag: 'i-lucide-tag',
+  filePlus: 'i-lucide-file-plus',
+  folderPlus: 'i-lucide-folder-plus',
+  movie: 'i-lucide-clapperboard',
+  clock: 'i-lucide-clock',
+  coffee: 'i-lucide-coffee',
+  globe: 'i-lucide-globe',
+  share: 'i-lucide-share',
+  link: 'i-lucide-link',
+  lock: 'i-lucide-lock',
+  filter: 'i-lucide-filter',
+  image: 'i-lucide-image',
+  camera: 'i-lucide-camera',
+  play: 'i-lucide-play',
+  terminal: 'i-lucide-terminal',
+  shield: 'i-lucide-shield',
+  sparkles: 'i-lucide-sparkles',
+  zap: 'i-lucide-zap',
+  package: 'i-lucide-package',
+  pin: 'i-lucide-pin',
+  palette: 'i-lucide-palette',
+  paintBucket: 'i-lucide-paint-bucket',
+  mic: 'i-lucide-mic',
+  heading: 'i-lucide-heading',
+  briefcase: 'i-lucide-briefcase',
+  bookOpen: 'i-lucide-book-open',
+  pencil: 'i-lucide-pencil',
+  undo: 'i-lucide-undo',
+  redo: 'i-lucide-redo'
+} as const
+
+export const studioExtraOverrides: Partial<Record<ThemeIcons, Partial<Record<keyof typeof STUDIO_EXTRA_DEFAULTS, string>>>> = {
+  // Pixel has no settings/cog (sliders stands in), no pie chart (generic
+  // chart) and no up-down chevron (sort). Everything else is a native match.
+  pixelarticons: {
+    bell: 'i-pixelarticons-bell',
+    calendar: 'i-pixelarticons-calendar',
+    settings: 'i-pixelarticons-sliders',
+    home: 'i-pixelarticons-home',
+    inbox: 'i-pixelarticons-inbox',
+    logout: 'i-pixelarticons-logout',
+    trash: 'i-pixelarticons-trash',
+    user: 'i-pixelarticons-user',
+    users: 'i-pixelarticons-users',
+    userPlus: 'i-pixelarticons-user-plus',
+    send: 'i-pixelarticons-send',
+    reply: 'i-pixelarticons-reply',
+    paperclip: 'i-pixelarticons-paperclip',
+    messageCircle: 'i-pixelarticons-message',
+    creditCard: 'i-pixelarticons-credit-card',
+    dollar: 'i-pixelarticons-dollar',
+    cart: 'i-pixelarticons-shopping-cart',
+    chart: 'i-pixelarticons-chart',
+    list: 'i-pixelarticons-list',
+    sort: 'i-pixelarticons-sort',
+    mail: 'i-pixelarticons-mail',
+    heart: 'i-pixelarticons-heart',
+    github: 'i-pixelarticons-github',
+    trendingUp: 'i-pixelarticons-trending-up',
+    trendingDown: 'i-pixelarticons-trending-down',
+    tag: 'i-pixelarticons-label',
+    filePlus: 'i-pixelarticons-file-plus',
+    folderPlus: 'i-pixelarticons-folder-plus',
+    movie: 'i-pixelarticons-movie',
+    clock: 'i-pixelarticons-clock',
+    coffee: 'i-pixelarticons-coffee',
+    globe: 'i-pixelarticons-globe',
+    share: 'i-pixelarticons-share',
+    link: 'i-pixelarticons-link',
+    lock: 'i-pixelarticons-lock',
+    filter: 'i-pixelarticons-filter',
+    image: 'i-pixelarticons-image',
+    camera: 'i-pixelarticons-camera',
+    play: 'i-pixelarticons-play',
+    terminal: 'i-pixelarticons-terminal',
+    shield: 'i-pixelarticons-shield',
+    sparkles: 'i-pixelarticons-sparkles',
+    zap: 'i-pixelarticons-zap',
+    package: 'i-pixelarticons-package',
+    pin: 'i-pixelarticons-pin',
+    // Pixel has no palette glyph, colors-swatch stands in.
+    palette: 'i-pixelarticons-colors-swatch',
+    paintBucket: 'i-pixelarticons-paint-bucket',
+    mic: 'i-pixelarticons-mic',
+    heading: 'i-pixelarticons-heading',
+    briefcase: 'i-pixelarticons-briefcase',
+    bookOpen: 'i-pixelarticons-book-open',
+    pencil: 'i-pixelarticons-pencil',
+    undo: 'i-pixelarticons-undo',
+    redo: 'i-pixelarticons-redo'
+  }
+}
diff --git a/docs/app/utils/theme/storage.ts b/docs/app/utils/theme/storage.ts
new file mode 100644
index 0000000000..214a567b16
--- /dev/null
+++ b/docs/app/utils/theme/storage.ts
@@ -0,0 +1,205 @@
+import type { ThemeDoc, StoredPaletteParams, StyleOptions } from './engine'
+import { THEME_DEFAULTS } from './engine'
+
+/**
+ * The font document: all three stacks plus the body treatment, exactly the
+ * doc's own shape. It used to be this type minus `sans`, because the sans
+ * shipped as its own `nuxt-ui-font` key long before the rest existed and the
+ * two never got folded back together.
+ */
+export type FontPrefs = NonNullable<ThemeDoc['font']>
+
+/**
+ * The theme's single persisted key. Every setting used to own a localStorage
+ * key of its own, which meant restores could interleave: the derived stores
+ * (the ramp behind a custom palette, the class bundle behind a style) could
+ * come back without the source that produced them, so each needed a self-heal
+ * to reconcile. One key writes atomically, so those states cannot disagree.
+ *
+ * Not a ThemeDoc: the doc is the EXPORT shape, diffed against a stock library
+ * install. This is a snapshot of runtime state, and hydrating it has to
+ * distribute values in a specific order (colors before paint, icons after
+ * hydration, see plugins/theme.ts). `currentDoc()` still derives the doc from
+ * this state whenever an export, a preset diff or a history entry needs one.
+ */
+export const THEME_STORAGE_KEY = 'nuxt-ui-theme'
+
+export interface StoredTheme {
+  primary?: string
+  neutral?: string
+  radius?: number
+  fontSize?: number
+  icons?: string
+  blackAsPrimary?: boolean
+  font?: FontPrefs
+  /** Semantic alias overrides (secondary, success, info, warning, error). */
+  colors?: Record<string, string>
+  /** Explicit per-component overrides, from presets, imports or the AI chat. */
+  components?: Record<string, Record<string, unknown>>
+  customColors?: Record<string, Record<string, string>>
+  cssVariables?: { light?: Record<string, string>, dark?: Record<string, string> }
+  style?: StyleOptions
+  /** The palette editor's curves and pins, the source the ramps derive from. */
+  paletteParams?: Partial<Record<string, StoredPaletteParams>>
+  /** The preset the per-section dirty and reset comparisons measure against. */
+  preset?: string
+}
+
+/**
+ * Every key the theme picker wrote before this became one key: the nine that
+ * are live on v4 today plus two this branch added (font size and the
+ * typography bag). The studio's own (style, palette params, preset) never
+ * left the branch and are not worth carrying.
+ *
+ * vueuse's `useLocalStorage` writes strings and numbers RAW, not JSON, so
+ * these read back per type rather than through JSON.parse.
+ */
+const LEGACY_KEYS = [
+  'nuxt-ui-primary', 'nuxt-ui-neutral', 'nuxt-ui-radius', 'nuxt-ui-font-size',
+  'nuxt-ui-font', 'nuxt-ui-icons', 'nuxt-ui-black-as-primary',
+  'nuxt-ui-font-prefs', 'nuxt-ui-ai-theme', 'nuxt-ui-custom-colors', 'nuxt-ui-css-variables'
+]
+
+function migrateLegacyTheme(): StoredTheme {
+  const read = (key: string) => window.localStorage.getItem(key) ?? undefined
+  const number = (key: string) => {
+    const value = Number.parseFloat(read(key) ?? '')
+    return Number.isFinite(value) ? value : undefined
+  }
+  const json = <T>(key: string): T | undefined => {
+    try {
+      const raw = read(key)
+      return raw ? JSON.parse(raw) as T : undefined
+    } catch {
+      return undefined
+    }
+  }
+
+  const extras = json<{ colors?: Record<string, string>, ui?: Record<string, Record<string, unknown>> }>('nuxt-ui-ai-theme')
+  const migrated: StoredTheme = {
+    primary: read('nuxt-ui-primary'),
+    neutral: read('nuxt-ui-neutral'),
+    radius: number('nuxt-ui-radius'),
+    fontSize: number('nuxt-ui-font-size'),
+    icons: read('nuxt-ui-icons'),
+    blackAsPrimary: read('nuxt-ui-black-as-primary') === 'true' || undefined,
+    // the family and the rest of the typography were two keys back then
+    font: normalizeFont({ ...json<Record<string, unknown>>('nuxt-ui-font-prefs'), sans: read('nuxt-ui-font') }),
+    colors: extras?.colors,
+    components: extras?.ui,
+    customColors: json('nuxt-ui-custom-colors'),
+    cssVariables: json('nuxt-ui-css-variables')
+  }
+
+  // Written back under the new key and the old ones dropped, so this runs
+  // exactly once per browser rather than on every load.
+  writeStoredTheme(migrated)
+  LEGACY_KEYS.forEach(key => window.localStorage.removeItem(key))
+  return migrated
+}
+
+const SAFE_FONT = /^[\w -]{1,50}$/
+
+/** Clamp to a range, or drop the value if it isn't a finite number. */
+function clamped(value: unknown, min: number, max: number): number | undefined {
+  const number = Number(value)
+  return Number.isFinite(number) ? Math.min(max, Math.max(min, number)) : undefined
+}
+
+/**
+ * Restores bypass `setFontPrefs`, so this is where a stored font document is
+ * made to satisfy the same invariants: no unusable family name, no
+ * out-of-range number, and no explicitly-stock family (which would otherwise
+ * read as a change forever, keeping the reset button lit).
+ */
+function normalizeFont(raw: unknown): FontPrefs | undefined {
+  if (!raw || typeof raw !== 'object') return undefined
+  const input = raw as Record<string, any>
+  const font: FontPrefs = {}
+
+  // `heading` was the old h1–h6 treatment. Only the family survived the
+  // rework, as the serif stack; the rest is dropped rather than kept as dead
+  // weight that every dirty check would still measure.
+  const family = (value: unknown) => typeof value === 'string' && SAFE_FONT.test(value) ? value : undefined
+  const sans = family(input.sans)
+  if (sans && sans !== THEME_DEFAULTS.font) font.sans = sans
+  const serif = family(input.serif) ?? family(input.heading?.font)
+  if (serif) font.serif = serif
+  const mono = family(input.mono)
+  if (mono) font.mono = mono
+
+  const weights: NonNullable<FontPrefs['weights']> = {}
+  for (const step of ['normal', 'medium', 'semibold', 'bold'] as const) {
+    const weight = clamped(input.weights?.[step], 100, 900)
+    if (weight !== undefined) weights[step] = weight
+  }
+  if (Object.keys(weights).length) font.weights = weights
+
+  if (input.uppercase) font.uppercase = true
+  if (input.italic) font.italic = true
+  const letterSpacing = clamped(input.letterSpacing, -0.2, 1)
+  if (letterSpacing !== undefined && letterSpacing !== 0) font.letterSpacing = letterSpacing
+  const lineHeight = clamped(input.lineHeight, 0.8, 3)
+  if (lineHeight !== undefined && lineHeight !== 1.5) font.lineHeight = lineHeight
+
+  return Object.keys(font).length ? font : undefined
+}
+
+/** Never throws: a corrupt or absent key reads as "no saved theme". */
+export function readStoredTheme(): StoredTheme {
+  if (!import.meta.client) return {}
+  try {
+    const raw = window.localStorage.getItem(THEME_STORAGE_KEY)
+    if (!raw) {
+      return LEGACY_KEYS.some(key => window.localStorage.getItem(key) !== null)
+        ? migrateLegacyTheme()
+        : {}
+    }
+    const parsed = JSON.parse(raw)
+    if (!parsed || typeof parsed !== 'object') return {}
+    // Interim shape from this key's first iteration, where the family was
+    // still a bare string beside a `fontPrefs` object. Never shipped, so this
+    // only has to survive a branch checkout, not a release.
+    if (typeof parsed.font === 'string' || parsed.fontPrefs) {
+      parsed.font = { ...parsed.fontPrefs, ...(typeof parsed.font === 'string' ? { sans: parsed.font } : {}) }
+      Reflect.deleteProperty(parsed, 'fontPrefs')
+    }
+    parsed.font = normalizeFont(parsed.font)
+    return parsed as StoredTheme
+  } catch {
+    return {}
+  }
+}
+
+/** An empty theme removes the key rather than storing `{}`. */
+export function writeStoredTheme(value: StoredTheme) {
+  if (!import.meta.client) return
+  const entries = Object.entries(value).filter(([, entry]) => {
+    if (entry === undefined) return false
+    if (entry && typeof entry === 'object') return Object.keys(entry).length > 0
+    return true
+  })
+  if (entries.length) {
+    window.localStorage.setItem(THEME_STORAGE_KEY, JSON.stringify(Object.fromEntries(entries)))
+  } else {
+    window.localStorage.removeItem(THEME_STORAGE_KEY)
+  }
+}
+
+/** Doc type re-exported so consumers don't reach past this module for it. */
+export type { ThemeDoc }
+
+/* ------------------------------------------------- shared identifiers -- */
+
+/** useState keys shared across composables. */
+export const THEME_STATE_KEYS = {
+  stylePrefs: 'nuxt-ui-style-prefs',
+  themePreset: 'nuxt-ui-theme-preset',
+  paletteParams: 'nuxt-ui-palette-params-state'
+} as const
+
+/** DOM ids of the style tags useHead owns and the FOUC scripts pre-fill. */
+export const THEME_TAG_IDS = {
+  cssVariables: 'nuxt-ui-css-variables',
+  customColors: 'nuxt-ui-custom-colors'
+} as const
diff --git a/docs/app/utils/theme/studio.ts b/docs/app/utils/theme/studio.ts
new file mode 100644
index 0000000000..c802536d8c
--- /dev/null
+++ b/docs/app/utils/theme/studio.ts
@@ -0,0 +1,94 @@
+import type { InjectionKey } from 'vue'
+import { resolveAlias, resolveShade, contrastRatio } from './engine'
+import type { ThemeDoc, Shade } from './engine'
+
+/** How deep a ThemeStudioSection sits, which decides how it behaves. */
+export const SECTION_DEPTH: InjectionKey<number> = Symbol('theme-studio-section-depth')
+
+/**
+ * A preset's primary ramp as a round swatch carrying its brand mark. The chip
+ * below paints the page (neutral) and inks the icon in primary; a circle small
+ * enough to read at a glance has to do the opposite, so the ramp fills it and
+ * the mark sits on top.
+ */
+export function themeSwatchStyle(doc: ThemeDoc) {
+  const shade = (alias: 'primary' | 'neutral', step: Shade) => resolveShade(doc, resolveAlias(doc, alias), step)
+  // black-as-primary has no ramp to gradient across, take the neutral ends
+  if (doc.blackAsPrimary) {
+    return {
+      '--swatch-light': `linear-gradient(135deg, ${shade('neutral', 700)}, ${shade('neutral', 950)})`,
+      '--swatch-dark': `linear-gradient(135deg, ${shade('neutral', 100)}, ${shade('neutral', 400)})`,
+      '--swatch-ink-light': 'white',
+      '--swatch-ink-dark': 'black'
+    }
+  }
+  // 300 → 600 rather than a tighter band: two neighbouring stops of one hue
+  // read as a flat fill, the range is what makes it a gradient.
+  const gradient = `linear-gradient(135deg, ${shade('primary', 300)}, ${shade('primary', 600)})`
+  // The mark sits over the gradient's midpoint. Every shipped preset's mid is
+  // light enough to take black, but a genuinely dark primary (navy, deep
+  // plum) would swallow it, so measure rather than hardcode.
+  // 500 as the reference: it always exists (tailwind ramps have no in-between
+  // stops) and sits at the darker end of the range, so it errs safe.
+  const base = shade('primary', 500)
+  const ink = !base || (contrastRatio(base, 'black') ?? 0) >= (contrastRatio(base, 'white') ?? 0) ? 'black' : 'white'
+  // A brand colour is the same colour in both modes, only the near-black
+  // ramp above has to flip to stay visible against the surface.
+  return {
+    '--swatch-light': gradient,
+    '--swatch-dark': gradient,
+    '--swatch-ink-light': ink,
+    '--swatch-ink-dark': ink
+  }
+}
+
+/** A preset's own ramp as a chip: its neutral as the page, its icon in its primary. */
+export function themeChipStyle(doc: ThemeDoc) {
+  const shade = (alias: 'primary' | 'neutral', step: Shade) => resolveShade(doc, resolveAlias(doc, alias), step)
+  return {
+    '--chip-bg-light': `linear-gradient(135deg, ${shade('neutral', 50)}, ${shade('neutral', 200)})`,
+    '--chip-bg-dark': `linear-gradient(135deg, ${shade('neutral', 900)}, ${shade('neutral', 800)})`,
+    '--chip-icon-light': doc.blackAsPrimary ? 'black' : shade('primary', 500),
+    '--chip-icon-dark': doc.blackAsPrimary ? 'white' : shade('primary', 400)
+  }
+}
+
+/** Palette names are ids, hyphens are word breaks, not part of the name. */
+export function paletteLabel(name: string): string {
+  return name.replace(/-/g, ' ')
+}
+
+/**
+ * interact-outside handler: clicks on studio chrome marked data-keep-panels
+ * (the color-mode switch) must not dismiss an open panel.
+ */
+export function keepPanels(event: Event) {
+  if ((event.target as HTMLElement | null)?.closest?.('[data-keep-panels]')) {
+    event.preventDefault()
+  }
+}
+
+/** Tailwind's stock weight ladder, set steps are absences at these values. */
+export const FONT_WEIGHT_DEFAULTS = { normal: 400, medium: 500, semibold: 600, bold: 700 } as const
+
+// Families whose preview faces are already requested, Public Sans is
+// bundled. Module-level so the controls, the preset menu and every search
+// batch share one ledger and no family is fetched twice.
+const loadedFontPreviews = new Set<string>(['Public Sans'])
+
+/**
+ * Load the listed families (Google Fonts, 400/700 only) so pickers can
+ * render themselves in the faces they offer. Incremental: each call adds
+ * one stylesheet covering only the families not yet requested, the font
+ * search feeds result batches through here as the user types.
+ */
+export function loadFontPreviews(fonts: readonly string[]) {
+  if (!import.meta.client) return
+  const families = fonts.filter(name => !loadedFontPreviews.has(name))
+  if (!families.length) return
+  families.forEach(name => loadedFontPreviews.add(name))
+  const link = document.createElement('link')
+  link.rel = 'stylesheet'
+  link.href = `https://fonts.googleapis.com/css2?${families.map(name => `family=${encodeURIComponent(name)}:wght@400;700`).join('&')}&display=swap`
+  document.head.appendChild(link)
+}
diff --git a/docs/app/utils/theme/tokens.ts b/docs/app/utils/theme/tokens.ts
new file mode 100644
index 0000000000..171040bc84
--- /dev/null
+++ b/docs/app/utils/theme/tokens.ts
@@ -0,0 +1,40 @@
+// The docs' own render baseline. It intentionally diverges from the library
+// defaults in one place: light `--ui-bg` follows the neutral ramp (set in
+// main.css) so tinted neutrals reach the page background. Export diffing
+// uses the engine's LIBRARY_TOKEN_DEFAULTS instead.
+export const cssVariableDefaults = {
+  light: {
+    '--ui-text-dimmed': 'var(--ui-color-neutral-400)',
+    '--ui-text-muted': 'var(--ui-color-neutral-500)',
+    '--ui-text-toned': 'var(--ui-color-neutral-600)',
+    '--ui-text': 'var(--ui-color-neutral-700)',
+    '--ui-text-highlighted': 'var(--ui-color-neutral-900)',
+    '--ui-text-inverted': 'white',
+    '--ui-bg': 'var(--ui-color-neutral-50)',
+    '--ui-bg-muted': 'var(--ui-color-neutral-50)',
+    '--ui-bg-elevated': 'var(--ui-color-neutral-100)',
+    '--ui-bg-accented': 'var(--ui-color-neutral-200)',
+    '--ui-bg-inverted': 'var(--ui-color-neutral-900)',
+    '--ui-border': 'var(--ui-color-neutral-200)',
+    '--ui-border-muted': 'var(--ui-color-neutral-200)',
+    '--ui-border-accented': 'var(--ui-color-neutral-300)',
+    '--ui-border-inverted': 'var(--ui-color-neutral-900)'
+  },
+  dark: {
+    '--ui-text-dimmed': 'var(--ui-color-neutral-500)',
+    '--ui-text-muted': 'var(--ui-color-neutral-400)',
+    '--ui-text-toned': 'var(--ui-color-neutral-300)',
+    '--ui-text': 'var(--ui-color-neutral-200)',
+    '--ui-text-highlighted': 'white',
+    '--ui-text-inverted': 'var(--ui-color-neutral-900)',
+    '--ui-bg': 'var(--ui-color-neutral-900)',
+    '--ui-bg-muted': 'var(--ui-color-neutral-800)',
+    '--ui-bg-elevated': 'var(--ui-color-neutral-800)',
+    '--ui-bg-accented': 'var(--ui-color-neutral-700)',
+    '--ui-bg-inverted': 'white',
+    '--ui-border': 'var(--ui-color-neutral-800)',
+    '--ui-border-muted': 'var(--ui-color-neutral-700)',
+    '--ui-border-accented': 'var(--ui-color-neutral-700)',
+    '--ui-border-inverted': 'white'
+  }
+} as const
diff --git a/docs/server/api/ai.post.ts b/docs/server/api/ai.post.ts
index 486a8bb988..627441ba17 100644
--- a/docs/server/api/ai.post.ts
+++ b/docs/server/api/ai.post.ts
@@ -5,7 +5,11 @@ import type { GatewayProviderOptions } from '@ai-sdk/gateway'
 import { z } from 'zod'
 import { tools as mcpToolDefinitions } from '#nuxt-mcp-toolkit/tools.mjs'
 import * as theme from '../../.nuxt/ui'
-import { themeIcons, cssVariableDefaults } from '../../app/utils/theme'
+import { themeIcons } from '../../app/utils/theme/icons'
+import { cssVariableDefaults } from '../../app/utils/theme/tokens'
+// The presets file itself, not the engine barrel: its only import is a type,
+// so this costs nothing beyond the preset data.
+import { presets } from '../../app/utils/theme/engine/presets'
 
 const componentNames = Object.keys(theme)
 
@@ -48,7 +52,10 @@ export interface ApplyThemeSettings {
   warning?: string
   error?: string
   radius?: number
-  font?: string
+  /** Tailwind's three stacks. Headings follow serif, code follows mono. */
+  fontSans?: string
+  fontSerif?: string
+  fontMono?: string
   blackAsPrimary?: boolean
   icons?: string
   customColors?: Record<string, Record<string, string>>
@@ -73,12 +80,14 @@ const applyTheme = tool({
       warning: { type: 'string', description: 'Warning color name' },
       error: { type: 'string', description: 'Error color name' },
       radius: { type: 'number', description: 'Border radius in rem: 0, 0.125, 0.25, 0.375, 0.5' },
-      font: { type: 'string', description: 'Font family name — any Google Font works (e.g. Public Sans, DM Sans, Geist, Inter, Poppins, Outfit, Raleway, Playfair Display, Nunito, JetBrains Mono, etc.)' },
+      fontSans: { type: 'string', description: 'Body font family (tailwind\'s --font-sans), the one every element inherits. Any Google Font works, and it does not have to be a sans (e.g. Public Sans, DM Sans, Geist, Inter, Poppins, Outfit, Playfair Display).' },
+      fontSerif: { type: 'string', description: 'Heading font family (tailwind\'s --font-serif; h1–h6 follow it). Any Google Font. Omit to keep headings on the body font.' },
+      fontMono: { type: 'string', description: 'Code font family (tailwind\'s --font-mono; code, kbd, pre and samp follow it). Any Google Font.' },
       blackAsPrimary: { type: 'boolean', description: 'Use solid black/white as primary color for a monochrome look' },
       icons: { type: 'string', description: 'Icon set for live preview: lucide (default), phosphor, or tabler. For exported code, any Iconify icon set can be suggested.' },
       customColors: {
         type: 'object',
-        description: 'Custom color palettes with shades 50-950 as hex values',
+        description: 'Custom color palettes with shades 50-950 as oklch(L% C H) values (e.g. oklch(62.3% 0.214 259.815)); hex also accepted',
         additionalProperties: {
           type: 'object',
           additionalProperties: { type: 'string' }
@@ -116,6 +125,16 @@ const resetTheme = tool({
   execute: async () => ({ reset: true })
 })
 
+const presetIds = presets.map(preset => preset.id) as [string, ...string[]]
+
+const applyPreset = tool({
+  description: `Apply one of the docs' built-in theme presets, whole and live. Use this ONLY when the user names a preset or asks for "the <name> look"; for any other theme request (a described aesthetic, a colour, a mood) design it yourself with \`applyTheme\` instead. A preset carries a full palette, token shades and component defaults that an \`applyTheme\` payload cannot express, so never try to rebuild one by hand. You can call \`applyTheme\` afterwards to tweak a preset you just applied. Available presets: ${presets.map(preset => `${preset.id} (${preset.name}: ${preset.description})`).join('; ')}.`,
+  inputSchema: z.object({
+    preset: z.enum(presetIds).describe('Id of the preset to apply.')
+  }),
+  execute: async ({ preset }) => ({ applied: true, preset })
+})
+
 const getComponentTheme = tool({
   description: 'Get the theme definition (slots, variants, compoundVariants, defaultVariants) for a specific Nuxt UI component. Call this when you need to know the available slots and customization options to suggest component-level theming.',
   inputSchema: z.object({
@@ -136,8 +155,8 @@ const getThemeGuide = tool({
   execute: async () => ({
     guide: `When users ask to change the theme, customize colors, or modify the appearance, use the \`applyTheme\` tool to apply changes live on this docs site. Only include properties that changed.
 
-When users ask for a complete theme, to change "all colors", or describe a broad aesthetic (e.g. "sakura-inspired theme"), you MUST set ALL of: primary, neutral, secondary, success, info, warning, error, radius, and font. You can change the icon set (lucide, phosphor, or tabler) if it really enhances the theme, but prefer keeping lucide as the default — it works well with most themes. You can optionally include component-level \`ui\` overrides for a more polished result — if you do, look up the component theme first with \`getComponentTheme\` and prefer \`defaultVariants\` (e.g. button size or variant) over slot class overrides. Create a cohesive design system, not just random colors:
-- Pick a **primary** that embodies the theme's identity. If no standard Tailwind color fits, use \`customColors\` to define a bespoke palette with all shades 50-950 as hex values — this is encouraged for creative/unique themes.
+When users ask for a complete theme, to change "all colors", or describe a broad aesthetic (e.g. "sakura-inspired theme"), you MUST set ALL of: primary, neutral, secondary, success, info, warning, error, radius, and fontSans. You can change the icon set (lucide, phosphor, or tabler) if it really enhances the theme, but prefer keeping lucide as the default — it works well with most themes. You can optionally include component-level \`ui\` overrides for a more polished result — if you do, look up the component theme first with \`getComponentTheme\` and prefer \`defaultVariants\` (e.g. button size or variant) over slot class overrides. Create a cohesive design system, not just random colors:
+- Pick a **primary** that embodies the theme's identity. If no standard Tailwind color fits, use \`customColors\` to define a bespoke palette with all shades 50-950 as \`oklch(L% C H)\` values, tailwind v4's native format, e.g. \`oklch(62.3% 0.214 259.815)\`. This is encouraged for creative/unique themes.
 - Pick a **secondary** that complements the primary (analogous or contrasting on the color wheel). Can also be a custom palette.
 - Pick **success/info/warning/error** that feel harmonious with the palette while staying semantically meaningful (success = green-ish, error = red-ish, warning = amber/yellow-ish, info = blue/cyan-ish). You can shift hues — e.g. \`lime\` for success in a nature theme, \`rose\` for error in a warm theme — but keep them recognizable.
 - For monochrome/black-and-white themes, keep semantic colors meaningful. Only primary, secondary, and neutral should go monochrome. Use \`blackAsPrimary: true\` for monochrome primary.
@@ -249,12 +268,16 @@ For Nuxt, wrap in \`defineAppConfig({ ui: { ... } })\`. For Vue, pass as \`ui({
   - **0.25** — balanced, default
   - **0.375** — rounded, friendly
   - **0.5** — pill-like, playful, soft
-- Font: any Google Font works, \`@nuxt/fonts\` auto-loads it. Pick a font that matches the theme's personality:
+- Fonts: three independent stacks, any Google Font works and \`@nuxt/fonts\` auto-loads it.
+  - \`fontSans\` — the body face everything inherits. Despite the name it takes any face, a serif body is a valid choice.
+  - \`fontSerif\` — headings (h1–h6) follow it. Set it only when you want headings to differ from the body; omit it and they match.
+  - \`fontMono\` — code, kbd, pre and samp follow it.
+  Pick faces that match the theme's personality:
   - Sans-serif (clean/modern): Inter, DM Sans, Geist, Public Sans, Outfit, Plus Jakarta Sans, Space Grotesk
-  - Serif (elegant/editorial): Playfair Display, Lora, Merriweather, Fraunces, Newsreader
+  - Serif (elegant/editorial): Playfair Display, Lora, Merriweather, Fraunces, Newsreader, Source Serif 4
   - Rounded (friendly/playful): Nunito, Quicksand, Varela Round
-  - Monospace (techy/dev): JetBrains Mono, Fira Code, IBM Plex Mono
-  ALWAYS change the font when creating a complete theme — don't leave the default unless it genuinely fits.
+  - Monospace (techy/dev): JetBrains Mono, Fira Code, IBM Plex Mono, Geist Mono
+  ALWAYS set \`fontSans\` when creating a complete theme — don't leave the default unless it genuinely fits. Pairing a display \`fontSerif\` with a plain body is the highest-leverage type choice available.
 - Icons: lucide (default), phosphor, or tabler for live preview. Any Iconify icon set works in the exported config. When suggesting a non-default icon set, include the FULL \`ui.icons\` mapping in the exported config and tell the user to install \`@iconify-json/{collection}\` (e.g. \`@iconify-json/ph\` for Phosphor). Required keys: ${Object.keys(themeIcons.phosphor).join(', ')}. Values use \`i-<set>-<name>\` format.
 
 **Component Theme Lookup:**
@@ -280,7 +303,16 @@ CRITICAL rules for component \`ui\` overrides:
 @import "@nuxt/ui";
 
 @theme {
-  --font-sans: 'FontName', sans-serif; /* only if font changed */
+  --font-sans: 'FontName', sans-serif; /* only if the body font changed */
+  --font-serif: 'FontName', serif;     /* only if headings differ from the body */
+  --font-mono: 'FontName', monospace;  /* only if the code font changed */
+}
+
+/* ONLY when --font-serif is set: nothing in tailwind consumes it, so headings
+   need this one rule. Omit the whole block otherwise, or every heading falls
+   back to Georgia. --font-sans and --font-mono need no rule at all. */
+@layer base {
+  h1, h2, h3, h4, h5, h6 { font-family: var(--font-serif); }
 }
 
 @theme static {
@@ -337,6 +369,7 @@ const tools = {
   ...mcpToolsToAiTools(),
   getThemeGuide,
   applyTheme,
+  applyPreset,
   resetTheme,
   getComponentTheme
 }
@@ -352,7 +385,7 @@ The user is using **${framework === 'vue' ? 'Vue' : 'Nuxt'}**. Tailor your answe
 Guidelines:
 - For documentation questions, ALWAYS use tools to search for information. Never rely on pre-trained knowledge for Nuxt UI APIs, props, or usage.
 - For questions about how to customize themes (e.g. "how do I customize colors?", "how does theming work?"), search the documentation like any other docs question.
-- When users ask you to APPLY a theme change live (e.g. "make it blue", "create a sakura theme", "change the font"), call \`getThemeGuide\` first for detailed instructions, then use \`applyTheme\` / \`resetTheme\`. Use your own judgment on aesthetics, color theory, and design — no need to search docs for that. Be decisive: pick colors/fonts/radius confidently and apply them.
+- When users ask you to APPLY a theme change live (e.g. "make it blue", "create a sakura theme", "change the font"), call \`getThemeGuide\` first for detailed instructions, then use \`applyTheme\` / \`resetTheme\`. Use your own judgment on aesthetics, color theory, and design — no need to search docs for that. Be decisive: pick colors/fonts/radius confidently and apply them. Only when the user names one of the built-in presets, or asks for "the <name> look", use \`applyPreset\` instead: a described aesthetic is yours to design, not a preset to match.
 - If a question is unrelated to Nuxt UI (e.g. general coding, off-topic), briefly answer if you can, but don't waste tool calls searching docs for it.
 - If no relevant information is found after searching, respond with "Sorry, I couldn't find information about that in the documentation."
 - Be concise and direct in your responses.
diff --git a/docs/server/api/fonts.json.get.ts b/docs/server/api/fonts.json.get.ts
new file mode 100644
index 0000000000..746d23ff52
--- /dev/null
+++ b/docs/server/api/fonts.json.get.ts
@@ -0,0 +1,20 @@
+type GoogleFont = {
+  name: string
+  category: string
+}
+
+/**
+ * The Google Fonts catalog, slimmed to what the theme studio's font picker
+ * needs (family name + category, popularity-ordered). Proxied because the
+ * metadata endpoint sends no CORS headers, and cached, the catalog moves
+ * a few families a month at most.
+ */
+export default defineCachedEventHandler(async (): Promise<GoogleFont[]> => {
+  const text = await $fetch<string>('https://fonts.google.com/metadata/fonts', { responseType: 'text' })
+  // Google JSON endpoints traditionally lead with an anti-hijacking prefix
+  const data = JSON.parse(text.replace(/^\)\]\}'/, ''))
+
+  return (data.familyMetadataList as Array<{ family: string, category: string, popularity?: number }>)
+    .sort((a, b) => (a.popularity ?? Number.MAX_SAFE_INTEGER) - (b.popularity ?? Number.MAX_SAFE_INTEGER))
+    .map(font => ({ name: font.family, category: font.category }))
+}, { name: 'google-fonts', maxAge: 60 * 60 * 24, swr: true })
diff --git a/package.json b/package.json
index a2abf12e61..ebe0079731 100644
--- a/package.json
+++ b/package.json
@@ -120,7 +120,7 @@
     "repl:build": "pnpm --filter './playgrounds/repl' build",
     "repl:prepare": "nuxt-module-build build --stub && mkdir -p .nuxt && echo '{\"compilerOptions\":{}}' > .nuxt/tsconfig.json",
     "docs": "nuxt dev docs --uiDev",
-    "docs:build": "nuxt build docs",
+    "docs:build": "NODE_OPTIONS=--max-old-space-size=8192 nuxt build docs",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "typecheck": "vue-tsc --noEmit && nuxt typecheck playgrounds/nuxt && nuxt typecheck docs && cd playgrounds/vue && vue-tsc --noEmit",
diff --git a/vitest.config.ts b/vitest.config.ts
index 0160f8ac81..8e8602640b 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -1,6 +1,6 @@
 import { fileURLToPath } from 'node:url'
 import { defineVitestProject } from '@nuxt/test-utils/config'
-import { defineConfig } from 'vitest/config'
+import { defineConfig, defaultExclude } from 'vitest/config'
 import vue from '@vitejs/plugin-vue'
 import codspeedPlugin from '@codspeed/vitest-plugin'
 import ui from './src/vite'
@@ -29,6 +29,10 @@ export default defineConfig({
           name: 'nuxt',
           dir: './test',
           include: ['components/**/**.spec.ts', 'composables/**.spec.ts', 'utils/**/**.spec.ts'],
+          // The docs theme-engine specs are pure functions over `docs/app/utils`,
+          // they need neither environment, so they run in `vue` (happy-dom,
+          // faster) only rather than twice.
+          exclude: [...defaultExclude, '**/theme-*.spec.ts'],
           // Benchmarks run in the `vue` project only (happy-dom, faster); keep them
           // out of the nuxt project so a bare `vitest bench` doesn't double-run them.
           benchmark: { include: [] },