docs(theme): exploring a full theme customizer

docs/app/app.vue

@@ -1,5 +1,8 @@
 <script setup lang="ts">
 const route = useRoute()
+
+/** The theme studio's UI-hiding fullscreen also hides the site chrome. */
+const studioFullscreen = useState('theme-studio-fullscreen', () => false)
 const appConfig = useAppConfig()
 const { style, link, color } = useTheme()
 
@@ -40,7 +43,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="!route.path.startsWith('/examples') && !(route.path === '/theme' && studioFullscreen)">
           <!-- <Banner /> -->
 
           <Header />
@@ -50,9 +53,10 @@ provide('navigation', rootNavigation)
           <NuxtPage />
         </NuxtLayout>
 
-        <template v-if="!route.path.startsWith('/examples')">
+        <template v-if="!route.path.startsWith('/examples') && route.path !== '/theme'">
           <Footer />
         </template>
+        <!-- footer stays off /theme: the studio is a fixed-height app page -->
       </div>
 
       <template v-if="!route.path.startsWith('/examples')">

docs/app/assets/css/main.css

@@ -6,6 +6,25 @@
 @theme static {
   --container-8xl: 90rem;
 
+  /* Every default-width border/ring/divide utility in the app compiles to
+     this var — the studio's width slider repaints the whole site through
+     one custom property instead of per-component class fragments. Exports
+     do the same thing statically (@theme --default-border-width). */
+  --default-border-width: var(--studio-border-width, 1px);
+  --default-ring-width: var(--studio-border-width, 1px);
+
+  /* Shadow ramp stays Tailwind-native by default — Inherit leaves the library
+     shadows completely untouched. Only under :root.shadow-custom does the
+     config-driven scale (--ui-shadow-c-*, defined below) take over each slot.
+     A var() fallback IS the native value, so the override is opt-in per size. */
+  --shadow-2xs: var(--ui-shadow-c-2xs, 0 1px rgb(0 0 0 / 0.05));
+  --shadow-xs: var(--ui-shadow-c-xs, 0 1px 2px 0 rgb(0 0 0 / 0.05));
+  --shadow-sm: var(--ui-shadow-c-sm, 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1));
+  --shadow-md: var(--ui-shadow-c-md, 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1));
+  --shadow-lg: var(--ui-shadow-c-lg, 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1));
+  --shadow-xl: var(--ui-shadow-c-xl, 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1));
+  --shadow-2xl: var(--ui-shadow-c-2xl, 0 25px 50px -12px rgb(0 0 0 / 0.25));
+
   --font-sans: 'Public Sans', sans-serif;
 
   --color-green-50: #EFFDF5;
@@ -54,3 +73,84 @@ html.dark .shiki span {
   -webkit-mask-image: var(--shiki-icon-url);
   mask-image: var(--shiki-icon-url);
 }
+
+/* Studio baselines. :where() keeps them at zero specificity: being
+   unlayered they still beat the library's @layer theme defaults, but any
+   user override from the theme studio (plain .light/.dark rules injected
+   via useHead) wins regardless of load order. */
+:where(:root:not(.dark), .light) {
+  /* hard-shadow treatment: a shadow, not a glow */
+  --ui-shadow-color: var(--ui-color-neutral-950);
+}
+
+/* The one shadow config the whole scale derives from: geometry (offset/blur/
+   spread), colour and opacity. The studio's sliders / presets override these —
+   a Soft preset keeps the blur, a Hard preset drops it to 0 and leans on offset.
+   The resting geometry is the crisp fallback presets rely on when they don't
+   set their own; the --shadow-* factors scale it per size. */
+:where(:root) {
+  --ui-shadow-offset-x: 3px;
+  --ui-shadow-offset-y: 3px;
+  --ui-shadow-blur: 0px;
+  --ui-shadow-spread: 0px;
+  --ui-shadow-final-hard: color-mix(in oklab, var(--ui-shadow-color) var(--ui-shadow-opacity, 100%), transparent);
+  /* The generalised ramp's alpha IS the opacity slider — uniform across sizes so
+     the slider reads true (100% is solid everywhere, for a neobrutalist theme;
+     low is subtle). Size is expressed through geometry (--ui-shadow-s-*), not by
+     fading small shadows, so a bold config stays bold on a badge as on a modal. */
+  --ui-shadow-alpha: var(--ui-shadow-opacity, 25%);
+  /* Per-size geometry scale (lg is the config's 1× reference); the offset/blur/
+     spread of the one config ride these so a tooltip's shadow is small and a
+     modal's large, from a single set of sliders. */
+  --ui-shadow-s-2xs: 0.15;
+  --ui-shadow-s-xs: 0.25;
+  --ui-shadow-s-sm: 0.4;
+  --ui-shadow-s-md: 0.65;
+  --ui-shadow-s-lg: 1;
+  --ui-shadow-s-xl: 1.5;
+  --ui-shadow-s-2xl: 2.2;
+  /* Composed press-effect shadows (button rests at 1×, hover sinks to ½×),
+     used as shadow-(--ui-shadow-hard*) so tailwind-merge can dedupe them
+     against stock shadow-sm/lg classes (it can't parse a full
+     shadow-[calc(...)_...] arbitrary value). */
+  --ui-shadow-hard: var(--ui-shadow-offset-x) var(--ui-shadow-offset-y) var(--ui-shadow-blur) var(--ui-shadow-spread) var(--ui-shadow-final-hard);
+  --ui-shadow-hard-half: calc(var(--ui-shadow-offset-x) / 2) calc(var(--ui-shadow-offset-y) / 2) var(--ui-shadow-blur) var(--ui-shadow-spread) var(--ui-shadow-final-hard);
+  /* Inner-shadow geometry defaults; shares --ui-shadow-color with the drop
+     treatment, with its own gentler opacity fallback. */
+  --ui-inner-shadow-offset-x: 0px;
+  --ui-inner-shadow-offset-y: 2px;
+  --ui-inner-shadow-blur: 4px;
+  --ui-inner-shadow-spread: 0px;
+  --ui-shadow-final-inner: color-mix(in oklab, var(--ui-inner-shadow-color, var(--ui-shadow-color)) var(--ui-inner-shadow-opacity, 15%), transparent);
+  --ui-inner-shadow: var(--ui-inner-shadow-offset-x) var(--ui-inner-shadow-offset-y) var(--ui-inner-shadow-blur) var(--ui-inner-shadow-spread) var(--ui-shadow-final-inner);
+}
+
+/* Custom shadow: one config — geometry (--ui-shadow-*), opacity (--ui-shadow-a-*)
+   and colour (--ui-shadow-color) — scaled per size (--ui-shadow-s-*) into the
+   ramp's override slots. Single-layer; blur 0 stays crisp, offset carries the
+   size ramp. Active only when the studio flags .shadow-custom on the root. */
+:root:where(.shadow-custom) {
+  --ui-shadow-c-2xs: calc(var(--ui-shadow-offset-x) * var(--ui-shadow-s-2xs)) calc(var(--ui-shadow-offset-y) * var(--ui-shadow-s-2xs)) calc(var(--ui-shadow-blur) * var(--ui-shadow-s-2xs)) calc(var(--ui-shadow-spread) * var(--ui-shadow-s-2xs)) color-mix(in oklab, var(--ui-shadow-color) var(--ui-shadow-alpha), transparent);
+  --ui-shadow-c-xs: calc(var(--ui-shadow-offset-x) * var(--ui-shadow-s-xs)) calc(var(--ui-shadow-offset-y) * var(--ui-shadow-s-xs)) calc(var(--ui-shadow-blur) * var(--ui-shadow-s-xs)) calc(var(--ui-shadow-spread) * var(--ui-shadow-s-xs)) color-mix(in oklab, var(--ui-shadow-color) var(--ui-shadow-alpha), transparent);
+  --ui-shadow-c-sm: calc(var(--ui-shadow-offset-x) * var(--ui-shadow-s-sm)) calc(var(--ui-shadow-offset-y) * var(--ui-shadow-s-sm)) calc(var(--ui-shadow-blur) * var(--ui-shadow-s-sm)) calc(var(--ui-shadow-spread) * var(--ui-shadow-s-sm)) color-mix(in oklab, var(--ui-shadow-color) var(--ui-shadow-alpha), transparent);
+  --ui-shadow-c-md: calc(var(--ui-shadow-offset-x) * var(--ui-shadow-s-md)) calc(var(--ui-shadow-offset-y) * var(--ui-shadow-s-md)) calc(var(--ui-shadow-blur) * var(--ui-shadow-s-md)) calc(var(--ui-shadow-spread) * var(--ui-shadow-s-md)) color-mix(in oklab, var(--ui-shadow-color) var(--ui-shadow-alpha), transparent);
+  --ui-shadow-c-lg: calc(var(--ui-shadow-offset-x) * var(--ui-shadow-s-lg)) calc(var(--ui-shadow-offset-y) * var(--ui-shadow-s-lg)) calc(var(--ui-shadow-blur) * var(--ui-shadow-s-lg)) calc(var(--ui-shadow-spread) * var(--ui-shadow-s-lg)) color-mix(in oklab, var(--ui-shadow-color) var(--ui-shadow-alpha), transparent);
+  --ui-shadow-c-xl: calc(var(--ui-shadow-offset-x) * var(--ui-shadow-s-xl)) calc(var(--ui-shadow-offset-y) * var(--ui-shadow-s-xl)) calc(var(--ui-shadow-blur) * var(--ui-shadow-s-xl)) calc(var(--ui-shadow-spread) * var(--ui-shadow-s-xl)) color-mix(in oklab, var(--ui-shadow-color) var(--ui-shadow-alpha), transparent);
+  --ui-shadow-c-2xl: calc(var(--ui-shadow-offset-x) * var(--ui-shadow-s-2xl)) calc(var(--ui-shadow-offset-y) * var(--ui-shadow-s-2xl)) calc(var(--ui-shadow-blur) * var(--ui-shadow-s-2xl)) calc(var(--ui-shadow-spread) * var(--ui-shadow-s-2xl)) color-mix(in oklab, var(--ui-shadow-color) var(--ui-shadow-alpha), transparent);
+}
+
+/* None: strip every default shadow-* to nothing so raw content (screenshots)
+   goes flat like the components do under the None treatment. */
+:root:where(.shadow-none) {
+  --ui-shadow-c-2xs: 0 0 transparent;
+  --ui-shadow-c-xs: 0 0 transparent;
+  --ui-shadow-c-sm: 0 0 transparent;
+  --ui-shadow-c-md: 0 0 transparent;
+  --ui-shadow-c-lg: 0 0 transparent;
+  --ui-shadow-c-xl: 0 0 transparent;
+  --ui-shadow-c-2xl: 0 0 transparent;
+}
+
+:where(.dark) {
+  --ui-shadow-color: black;
+}

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(' ')

docs/app/components/chat/Chat.vue

@@ -242,7 +242,7 @@ defineShortcuts({
           icon="i-lucide-rotate-ccw"
           color="neutral"
           variant="ghost"
-          @click="resetTheme"
+          @click="resetTheme()"
         />
       </UTooltip>
 

docs/app/components/header/Header.vue

@@ -3,13 +3,21 @@ 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) {
     track('AI Chat Opened', { source: 'header' })
   }
   open.value = !open.value
 }
+
+// On /theme the header center becomes the studio's view switcher.
+const isStudio = computed(() => route.path === '/theme')
+
+const viewListOpen = ref(false)
 </script>
 
 <!-- eslint-disable vue/no-template-shadow -->
@@ -28,7 +36,8 @@ function toggleChat() {
       <VersionMenu />
     </template>
 
-    <UNavigationMenu :items="desktopLinks" variant="link" content-orientation="vertical" />
+    <ThemeStudioViewSwitcher v-if="isStudio" v-model:open="viewListOpen" />
+    <UNavigationMenu v-else :items="desktopLinks" variant="link" content-orientation="vertical" />
 
     <template #right>
       <UTooltip text="Search" :kbds="['meta', 'K']" ignore-non-keyboard-focus>
@@ -39,21 +48,21 @@ 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="Open on GitHub" class="hidden lg:flex">
         <UButton
           color="neutral"
           variant="ghost"
           to="https://github.com/nuxt/ui"
           target="_blank"
-          icon="i-simple-icons-github"
+          :icon="studioIcons.github"
           aria-label="GitHub"
         />
       </UTooltip>

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>

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>

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>