@commonpub/layer 0.66.0 → 0.68.0

package/app.vue

@@ -4,4 +4,18 @@
   <NuxtLayout>
     <NuxtPage />
   </NuxtLayout>
+  <!-- Film-grain overlay. Invisible unless the active theme sets --grain > 0 (default 0). -->
+  <div class="cpub-grain" aria-hidden="true" />
 </template>
+
+<style>
+.cpub-grain {
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  z-index: 9999;
+  opacity: var(--grain, 0);
+  background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.8' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");
+}
+@media print { .cpub-grain { display: none; } }
+</style>

package/components/admin/theme/studio/AdminThemeStudio.vue

@@ -20,6 +20,9 @@ import {
   randomizeRecipe,
   randomName,
   buildPalette,
+  harmonyColors,
+  contrast,
+  wcag,
   COLOR_VIBES,
   TYPE_VIBES,
   SHAPE_PRESETS,
@@ -30,7 +33,7 @@ import {
   type HarmonyScheme,
 } from '@commonpub/theme-studio';
 
-const props = defineProps<{ recipe?: ThemeRecipe }>();
+const props = defineProps<{ recipe?: ThemeRecipe; name?: string }>();
 
 const emit = defineEmits<{
   generate: [{
@@ -40,8 +43,9 @@ const emit = defineEmits<{
     parentTheme: 'base' | 'dark';
     isDark: boolean;
   }];
-  finish: [];
+  finish: [{ apply: boolean }];
   roll: [{ name: string }];
+  rename: [string];
 }>();
 
 const recipe = ref<ThemeRecipe>(props.recipe ? { ...props.recipe } : defaultRecipe());
@@ -50,7 +54,8 @@ const STEPS = [
   { kicker: 'Color', q: 'Pick a vibe, or your colors.' },
   { kicker: 'Type', q: 'Pick a type vibe, or fonts.' },
   { kicker: 'Shape', q: 'Rounded or sharp?' },
-  { kicker: 'Feel', q: 'Spacing, density, motion.' },
+  { kicker: 'Feel', q: 'Spacing, density, texture, motion.' },
+  { kicker: 'Finish', q: 'Name it and save.' },
 ] as const;
 const step = ref(0);
 
@@ -58,6 +63,17 @@ const colorTab = ref<'vibe' | 'custom'>(props.recipe ? 'custom' : 'vibe');
 const typeTab = ref<'vibe' | 'custom'>(props.recipe ? 'custom' : 'vibe');
 const colorVibe = ref(0);
 const typeVibe = ref(0);
+const useSecondary = ref(Boolean(props.recipe?.secondary));
+const applyDefault = ref(false);
+
+const SCHEMES: { val: HarmonyScheme; label: string }[] = [
+  { val: 'analogous', label: 'Analogous' },
+  { val: 'complementary', label: 'Complement' },
+  { val: 'triadic', label: 'Triadic' },
+  { val: 'split', label: 'Split' },
+  { val: 'tetradic', label: 'Tetradic' },
+  { val: 'monochrome', label: 'Mono' },
+];
 
 // --- Emit on every change ---------------------------------------------
 
@@ -73,22 +89,32 @@ function emitGenerate(): void {
 }
 watch(recipe, emitGenerate, { deep: true });
 
-// --- Vibe swatch previews ---------------------------------------------
+// --- Live WCAG audit (reassurance + catch extreme hand-picks) ----------
+
+const auditTokens = computed(() => recipeToTokens(recipe.value).tokens);
+function band(fg: string, bg: string): { ratio: string; band: string; ok: boolean } {
+  const r = contrast(fg, bg);
+  const b = wcag(r);
+  return { ratio: r.toFixed(1), band: b, ok: b !== 'FAIL' };
+}
+const auditText = computed(() => band(auditTokens.value['text']!, auditTokens.value['bg']!));
+const auditLink = computed(() => band(auditTokens.value['color-link']!, auditTokens.value['bg']!));
+
+// --- Vibe swatch + harmony-family previews ----------------------------
 
-// The emitted CommonPub token set derives entirely from accent (hue+sat) +
-// mode + the scale/shape/feel knobs — neutrals/text are accent-tinted. The
-// harmony scheme only seeds the preview swatch family below; it does NOT
-// change the generated theme (CommonPub has no secondary-accent token), so
-// the wizard doesn't expose a scheme/secondary control. `scheme` stays on the
-// recipe (from the vibe presets) for forward-compat.
 function miniPal(accent: string, scheme: HarmonyScheme, mode: 'light' | 'dark'): string[] {
   const p = buildPalette({ accent, scheme, mode }).sem;
-  return [p.accent, p.surface2, p.surface, p.bg];
+  return [p.accent, p.secondary, p.surface2, p.bg];
 }
 function palStrip(accent: string, scheme: HarmonyScheme, mode: 'light' | 'dark'): string[] {
   const p = buildPalette({ accent, scheme, mode }).sem;
-  return [p.bg, p.surface, p.surface2, p.accent, p.text];
+  return [p.bg, p.surface, p.accent, p.secondary, p.text];
 }
+/** The accent + its harmony companions — the "suggested family" strip. */
+const familyStrip = computed<string[]>(() => [
+  recipe.value.accent,
+  ...harmonyColors(recipe.value.accent, recipe.value.scheme),
+]);
 
 // --- Color actions -----------------------------------------------------
 
@@ -96,10 +122,52 @@ function applyPalette(accent: string, scheme: HarmonyScheme, mode: 'light' | 'da
   recipe.value.accent = accent;
   recipe.value.scheme = scheme;
   recipe.value.mode = mode;
+  recipe.value.secondary = undefined;
+  useSecondary.value = false;
 }
 function onAccentHex(v: string): void {
   if (/^#?[0-9a-fA-F]{6}$/.test(v)) recipe.value.accent = v[0] === '#' ? v : `#${v}`;
 }
+function onSecondaryHex(v: string): void {
+  if (/^#?[0-9a-fA-F]{6}$/.test(v)) recipe.value.secondary = v[0] === '#' ? v : `#${v}`;
+}
+function toggleSecondary(): void {
+  useSecondary.value = !useSecondary.value;
+  recipe.value.secondary = useSecondary.value ? recipe.value.secondary ?? '#8b5cf6' : undefined;
+}
+
+/** Pull a dominant, vivid-ish accent out of an uploaded image (client-only). */
+function onImagePick(e: Event): void {
+  const file = (e.target as HTMLInputElement).files?.[0];
+  if (!file || typeof document === 'undefined') return;
+  const url = URL.createObjectURL(file);
+  const img = new Image();
+  img.onload = (): void => {
+    const cv = document.createElement('canvas');
+    const w = (cv.width = 48);
+    const h = (cv.height = 48);
+    const ctx = cv.getContext('2d');
+    URL.revokeObjectURL(url);
+    if (!ctx) return;
+    ctx.drawImage(img, 0, 0, w, h);
+    const d = ctx.getImageData(0, 0, w, h).data;
+    let best: [number, number, number] | null = null;
+    let bestScore = -1;
+    for (let i = 0; i < d.length; i += 4) {
+      const r = d[i]!, g = d[i + 1]!, b = d[i + 2]!, a = d[i + 3]!;
+      if (a < 200) continue;
+      const mx = Math.max(r, g, b), mn = Math.min(r, g, b);
+      const l = (mx + mn) / 2 / 255;
+      const sat = mx === mn ? 0 : (mx - mn) / 255;
+      const score = sat * (1 - Math.abs(l - 0.5) * 1.1); // saturated + mid-light wins
+      if (score > bestScore) { bestScore = score; best = [r, g, b]; }
+    }
+    if (best) {
+      recipe.value.accent = '#' + best.map((c) => c.toString(16).padStart(2, '0')).join('');
+    }
+  };
+  img.src = url;
+}
 
 // --- Type actions ------------------------------------------------------
 
@@ -114,6 +182,7 @@ function roll(): void {
   recipe.value = randomizeRecipe(seed);
   colorTab.value = 'vibe';
   typeTab.value = 'vibe';
+  useSecondary.value = Boolean(recipe.value.secondary);
   emit('roll', { name: randomName(seed) });
 }
 
@@ -121,12 +190,14 @@ function roll(): void {
 
 const isLast = computed(() => step.value === STEPS.length - 1);
 function next(): void {
-  if (isLast.value) emit('finish');
-  else step.value++;
+  if (!isLast.value) step.value++;
 }
 function back(): void {
   if (step.value > 0) step.value--;
 }
+function finishWith(apply: boolean): void {
+  emit('finish', { apply });
+}
 </script>
 
 <template>
@@ -202,24 +273,45 @@ function back(): void {
 
         <template v-else>
           <label class="cpub-studio-field">
-            <span class="cpub-studio-lbl">Mode</span>
+            <span class="cpub-studio-lbl">Default mode <span class="cpub-studio-hint">both are saved</span></span>
             <span class="cpub-studio-seg">
               <button type="button" :class="{ on: recipe.mode === 'light' }" @click="recipe.mode = 'light'">Light</button>
               <button type="button" :class="{ on: recipe.mode === 'dark' }" @click="recipe.mode = 'dark'">Dark</button>
             </span>
           </label>
           <label class="cpub-studio-field">
-            <span class="cpub-studio-lbl">Accent</span>
+            <span class="cpub-studio-lbl">Accent <span class="cpub-studio-hint">from image…</span></span>
             <span class="cpub-studio-colorrow">
               <input type="color" :value="recipe.accent" class="cpub-studio-colorpick" @input="recipe.accent = ($event.target as HTMLInputElement).value" />
               <input type="text" :value="recipe.accent" maxlength="7" class="cpub-studio-input cpub-studio-mono" @input="onAccentHex(($event.target as HTMLInputElement).value)" />
+              <label class="cpub-studio-imgbtn" title="Extract an accent from an image or logo">
+                <i class="fa-solid fa-image" aria-hidden="true" />
+                <input type="file" accept="image/*" hidden @change="onImagePick" />
+              </label>
+            </span>
+          </label>
+          <label class="cpub-studio-field">
+            <span class="cpub-studio-lbl">Color family <span class="cpub-studio-hint">harmony</span></span>
+            <span class="cpub-studio-seg cpub-studio-seg-wrap">
+              <button v-for="sc in SCHEMES" :key="sc.val" type="button" :class="{ on: recipe.scheme === sc.val }" @click="recipe.scheme = sc.val">{{ sc.label }}</button>
+            </span>
+          </label>
+          <div class="cpub-studio-field">
+            <span class="cpub-studio-lbl">Suggested family</span>
+            <span class="cpub-studio-family">
+              <span v-for="(c, i) in familyStrip" :key="i" :style="{ background: c }" :title="c" />
+            </span>
+          </div>
+          <div class="cpub-studio-toggle-line">
+            <span class="cpub-studio-lbl">Hand-pick secondary</span>
+            <button type="button" class="cpub-studio-switch" :class="{ on: useSecondary }" :aria-pressed="useSecondary" @click="toggleSecondary" />
+          </div>
+          <label v-if="useSecondary" class="cpub-studio-field">
+            <span class="cpub-studio-colorrow">
+              <input type="color" :value="recipe.secondary" class="cpub-studio-colorpick" @input="recipe.secondary = ($event.target as HTMLInputElement).value" />
+              <input type="text" :value="recipe.secondary" maxlength="7" class="cpub-studio-input cpub-studio-mono" @input="onSecondaryHex(($event.target as HTMLInputElement).value)" />
             </span>
           </label>
-          <p class="cpub-studio-note">
-            Surfaces, text, borders, and states are derived from your accent and mode. Switch
-            Light / Dark in the preview to see both. Fine-tune any individual color later in
-            the advanced editor.
-          </p>
         </template>
       </div>
 
@@ -310,7 +402,7 @@ function back(): void {
       </div>
 
       <!-- STEP 4: FEEL -->
-      <div v-else>
+      <div v-else-if="step === 3">
         <label class="cpub-studio-field">
           <span class="cpub-studio-lbl">Spacing base</span>
           <span class="cpub-studio-seg">
@@ -324,17 +416,41 @@ function back(): void {
             <button v-for="d in (['compact','balanced','spacious'] as const)" :key="d" type="button" :class="{ on: recipe.density === d }" @click="recipe.density = d">{{ d }}</button>
           </span>
         </label>
+        <label class="cpub-studio-field">
+          <span class="cpub-studio-lbl">Grain <span class="cpub-studio-val">{{ Math.round(recipe.texture * 100) }}%</span></span>
+          <input type="range" min="0" max="12" :value="Math.round(recipe.texture * 100)" class="cpub-studio-range" @input="recipe.texture = Number(($event.target as HTMLInputElement).value) / 100" />
+        </label>
         <label class="cpub-studio-field">
           <span class="cpub-studio-lbl">Motion</span>
           <span class="cpub-studio-seg">
             <button v-for="m in (['sharp','snappy','smooth'] as const)" :key="m" type="button" :class="{ on: recipe.motion === m }" @click="recipe.motion = m">{{ m }}</button>
           </span>
         </label>
+      </div>
+
+      <!-- STEP 5: FINISH -->
+      <div v-else>
+        <label class="cpub-studio-field">
+          <span class="cpub-studio-lbl">Theme name</span>
+          <input
+            type="text"
+            :value="props.name"
+            class="cpub-studio-input"
+            placeholder="My theme"
+            @input="emit('rename', ($event.target as HTMLInputElement).value)"
+          />
+        </label>
+        <div class="cpub-studio-toggle-line">
+          <span class="cpub-studio-lbl">Save &amp; apply as the site default</span>
+          <button type="button" class="cpub-studio-switch" :class="{ on: applyDefault }" :aria-pressed="applyDefault" @click="applyDefault = !applyDefault" />
+        </div>
         <p class="cpub-studio-note">
-          Studio saves a matching light + dark pair, each tuned for its mode. Finish to drop
-          into the advanced editor with every token populated; re-open Studio any time, or
-          fine-tune individual tokens by hand.
+          Studio saves a matching light + dark pair, each tuned for its mode. After saving you can
+          re-open Studio any time, or fine-tune individual tokens in the advanced editor.
         </p>
+        <button type="button" class="cpub-btn cpub-btn-primary cpub-studio-save" @click="finishWith(applyDefault)">
+          <i class="fa-solid fa-floppy-disk" aria-hidden="true" /> {{ applyDefault ? 'Save & apply theme' : 'Save theme' }}
+        </button>
       </div>
     </div>
 
@@ -342,9 +458,12 @@ function back(): void {
       <button type="button" class="cpub-btn cpub-btn-sm" :disabled="step === 0" @click="back">
         <i class="fa-solid fa-arrow-left" aria-hidden="true" /> Back
       </button>
-      <button type="button" class="cpub-btn cpub-btn-sm cpub-btn-primary" @click="next">
-        <template v-if="isLast"><i class="fa-solid fa-check" aria-hidden="true" /> Generate &amp; edit</template>
-        <template v-else>Next <i class="fa-solid fa-arrow-right" aria-hidden="true" /></template>
+      <span class="cpub-studio-audit" :title="`text ${auditText.ratio}:1, links ${auditLink.ratio}:1`">
+        <span class="cpub-studio-chip" :class="auditText.ok ? 'ok' : 'bad'">text {{ auditText.band }}</span>
+        <span class="cpub-studio-chip" :class="auditLink.ok ? 'ok' : 'bad'">links {{ auditLink.band }}</span>
+      </span>
+      <button v-if="!isLast" type="button" class="cpub-btn cpub-btn-sm cpub-btn-primary" @click="next">
+        Next <i class="fa-solid fa-arrow-right" aria-hidden="true" />
       </button>
     </footer>
   </div>
@@ -422,7 +541,28 @@ function back(): void {
 .cpub-studio-range:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
 
 .cpub-studio-note { font-size: var(--text-sm); color: var(--text-dim); line-height: var(--leading-snug); margin: var(--space-4) 0 0; }
-
-.cpub-studio-foot { display: flex; gap: var(--space-2); padding: var(--space-3) var(--space-4); border-top: var(--border-width-default) solid var(--border); }
-.cpub-studio-foot .cpub-btn:last-child { margin-left: auto; }
+.cpub-studio-hint { float: right; color: var(--text-faint); text-transform: none; letter-spacing: 0; }
+
+.cpub-studio-imgbtn { display: inline-grid; place-items: center; width: 36px; height: 36px; flex-shrink: 0; border: var(--border-width-thin) solid var(--border2); background: var(--surface2); color: var(--text-dim); cursor: pointer; }
+.cpub-studio-imgbtn:hover { border-color: var(--accent); color: var(--accent); }
+
+.cpub-studio-family { display: flex; height: 26px; border: var(--border-width-thin) solid var(--border2); overflow: hidden; }
+.cpub-studio-family span { flex: 1; }
+
+/* hand-pick secondary toggle */
+.cpub-studio-toggle-line { display: flex; align-items: center; justify-content: space-between; margin-top: var(--space-3); }
+.cpub-studio-toggle-line .cpub-studio-lbl { margin-bottom: 0; }
+.cpub-studio-switch { position: relative; width: 38px; height: 20px; background: var(--surface3); border: var(--border-width-thin) solid var(--border2); cursor: pointer; flex-shrink: 0; }
+.cpub-studio-switch::after { content: ''; position: absolute; top: 1px; left: 1px; width: 14px; height: 14px; background: var(--text-faint); transition: transform var(--transition-fast); }
+.cpub-studio-switch.on { background: var(--accent-bg); border-color: var(--accent); }
+.cpub-studio-switch.on::after { transform: translateX(18px); background: var(--accent); }
+
+.cpub-studio-save { width: 100%; justify-content: center; margin-top: var(--space-4); }
+
+.cpub-studio-foot { display: flex; align-items: center; gap: var(--space-2); padding: var(--space-3) var(--space-4); border-top: var(--border-width-default) solid var(--border); }
+.cpub-studio-audit { display: flex; gap: 4px; margin-left: auto; }
+.cpub-studio-chip { font-family: var(--font-mono); font-size: 9px; font-weight: var(--font-weight-bold); letter-spacing: var(--tracking-wide); text-transform: uppercase; padding: 2px 6px; border: var(--border-width-thin) solid; }
+.cpub-studio-chip.ok { color: var(--green); border-color: var(--green); }
+.cpub-studio-chip.bad { color: var(--red); border-color: var(--red); }
+.cpub-studio-foot .cpub-btn-primary { margin-left: var(--space-2); }
 </style>

package/composables/useTheme.ts

@@ -29,6 +29,7 @@ export function useTheme(): {
   const themeId = useState<string>('cpub-theme', () => 'base');
   const instanceDefault = useState<string>('cpub-instance-theme', () => 'base');
   const isDark = useState<boolean>('cpub-dark-mode', () => false);
+  const themePair = useState<{ lightAttr: string; darkAttr: string } | null>('cpub-theme-pair', () => null);
   const schemeCookie = useCookie('cpub-color-scheme', {
     maxAge: 31536000,
     path: '/',
@@ -44,9 +45,21 @@ export function useTheme(): {
       schemeCookie.value = dark ? 'dark' : 'light';
     }
 
+    // Custom light/dark PAIR: both variants' tokens are injected (scoped to
+    // their data-theme attr), so flip the attribute client-side for an instant
+    // switch — exactly like built-in families. (This is the fix for "the site
+    // light/dark toggle didn't switch a custom theme".)
+    if (themePair.value) {
+      const newTheme = dark ? themePair.value.darkAttr : themePair.value.lightAttr;
+      themeId.value = newTheme;
+      if (import.meta.client) {
+        document.documentElement.setAttribute('data-theme', newTheme);
+        $fetch('/api/profile/theme', { method: 'PUT', body: { themeId: newTheme } }).catch(() => {});
+      }
+      return;
+    }
+
     // Built-in family flip is purely client-side for snappy UX.
-    // Custom/registered themes need a server round-trip on next nav
-    // (the server reads the new cookie and picks the right pair).
     if (THEME_TO_FAMILY[instanceDefault.value]) {
       const family = THEME_TO_FAMILY[instanceDefault.value]!;
       const variants = FAMILY_VARIANTS[family] ?? FAMILY_VARIANTS.classic!;
@@ -61,7 +74,8 @@ export function useTheme(): {
         }).catch(() => {});
       }
     } else if (import.meta.client) {
-      // Custom theme: just persist preference; server will pick the variant on next request
+      // Single custom / registered theme with no pair: persist preference only;
+      // the server picks any declared variant on the next request.
       $fetch('/api/profile/theme', {
         method: 'PUT',
         body: { themeId: instanceDefault.value },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonpub/layer",
-  "version": "0.66.0",
+  "version": "0.68.0",
   "type": "module",
   "main": "./nuxt.config.ts",
   "files": [
@@ -56,14 +56,14 @@
     "@commonpub/auth": "0.8.0",
     "@commonpub/config": "0.20.0",
     "@commonpub/docs": "0.6.3",
-    "@commonpub/protocol": "0.13.0",
-    "@commonpub/editor": "0.7.11",
     "@commonpub/explainer": "0.7.15",
-    "@commonpub/schema": "0.36.0",
-    "@commonpub/ui": "0.11.2",
+    "@commonpub/editor": "0.7.11",
+    "@commonpub/learning": "0.5.2",
+    "@commonpub/schema": "0.37.0",
+    "@commonpub/protocol": "0.13.0",
     "@commonpub/server": "2.83.0",
-    "@commonpub/theme-studio": "0.2.0",
-    "@commonpub/learning": "0.5.2"
+    "@commonpub/ui": "0.12.0",
+    "@commonpub/theme-studio": "0.3.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",

package/pages/admin/theme/edit/[id].vue

@@ -17,7 +17,7 @@
  */
 import { computed, onMounted, onBeforeUnmount, ref } from 'vue';
 import { TOKEN_GROUP_LABELS, TOKEN_GROUP_ORDER, tokensByGroup } from '@commonpub/ui';
-import { googleHref, recipeToTokens, type ThemeRecipe } from '@commonpub/theme-studio';
+import { googleHref, recipeToTokens, buildBrief, buildTokensJson, type ThemeRecipe } from '@commonpub/theme-studio';
 
 definePageMeta({ layout: 'admin', middleware: 'auth' });
 
@@ -174,9 +174,17 @@ function onStudioGenerate(payload: {
   dirty.value = true;
 }
 
-/** "Generate & edit" — leave Studio for the granular token editor. */
-function onStudioFinish(): void {
+/** Wizard "Save" — persist (+ sibling pair) and optionally apply as default,
+ *  then drop into the advanced editor. */
+function onStudioFinish(payload: { apply: boolean }): void {
   studioMode.value = false;
+  void save({ apply: payload.apply });
+}
+
+/** Name typed in the wizard's finish step. */
+function onStudioRename(name: string): void {
+  draft.value.name = name;
+  dirty.value = true;
 }
 
 /** Dice roll suggests a name; adopt it only if the user hasn't named it. */
@@ -330,6 +338,34 @@ async function applyAndSave(): Promise<void> {
   await save({ apply: true });
 }
 
+/** Download a text artifact (brief / tokens) built from the current draft. */
+function downloadText(filename: string, content: string, mime: string): void {
+  if (typeof document === 'undefined') return;
+  const blob = new Blob([content], { type: mime });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  URL.revokeObjectURL(url);
+}
+function exportBrief(): void {
+  downloadText(
+    `${draft.value.id}-brief.md`,
+    buildBrief({ name: draft.value.name, description: draft.value.description }, draft.value.tokens),
+    'text/markdown',
+  );
+}
+function exportTokens(): void {
+  downloadText(
+    `${draft.value.id}.tokens.json`,
+    buildTokensJson({ name: draft.value.name }, draft.value.tokens),
+    'application/json',
+  );
+}
+
 function exportTheme(): void {
   // Snapshot the in-progress draft (unsaved tokens included) so the
   // admin can export-while-editing without committing first.
@@ -429,7 +465,10 @@ onBeforeUnmount(() => {
           </select>
         </label>
 
-        <label class="theme-editor-field theme-editor-field-toggle">
+        <!-- Mode pill only for hand-authored themes. Studio themes are a managed
+             light+dark pair — there's no single "mode" to pick, and the site's
+             Light/Dark toggle switches the pair for visitors. -->
+        <label v-if="!draft.recipe" class="theme-editor-field theme-editor-field-toggle">
           <span class="theme-editor-field-label">Mode</span>
           <div class="theme-editor-mode-pill" role="group">
             <button
@@ -447,7 +486,7 @@ onBeforeUnmount(() => {
           </div>
         </label>
 
-        <label v-if="pairCandidates.length" class="theme-editor-field">
+        <label v-if="!draft.recipe && pairCandidates.length" class="theme-editor-field">
           <span class="theme-editor-field-label">Pair with</span>
           <select v-model="draft.pairId" class="theme-editor-input" @change="onMetaChange">
             <option :value="undefined">- none -</option>
@@ -479,9 +518,16 @@ onBeforeUnmount(() => {
         <span v-if="modifiedTotal > 0" class="theme-editor-modified">
           {{ modifiedTotal }} token{{ modifiedTotal === 1 ? '' : 's' }} customized
         </span>
-        <button class="cpub-btn cpub-btn-sm" @click="exportTheme" title="Download .cpub-theme.json">
-          <i class="fa-solid fa-file-export" aria-hidden="true" /> Export
-        </button>
+        <details class="theme-editor-export">
+          <summary class="cpub-btn cpub-btn-sm">
+            <i class="fa-solid fa-file-export" aria-hidden="true" /> Export
+          </summary>
+          <div class="theme-editor-export-menu">
+            <button type="button" @click="exportTheme"><i class="fa-solid fa-file-code" aria-hidden="true" /> Theme (.cpub-theme.json)</button>
+            <button type="button" @click="exportBrief"><i class="fa-solid fa-robot" aria-hidden="true" /> AI brief (.md)</button>
+            <button type="button" @click="exportTokens"><i class="fa-solid fa-file-lines" aria-hidden="true" /> Tokens (.json)</button>
+          </div>
+        </details>
         <button class="cpub-btn cpub-btn-sm" :disabled="saving || !dirty" @click="() => save()">
           <i :class="['fa-solid', saving ? 'fa-circle-notch fa-spin' : 'fa-floppy-disk']" aria-hidden="true" />
           {{ saving ? 'Saving…' : 'Save' }}
@@ -514,14 +560,18 @@ onBeforeUnmount(() => {
         v-if="studioMode"
         class="theme-editor-studio"
         :recipe="draft.recipe"
+        :name="draft.name"
         @generate="onStudioGenerate"
         @finish="onStudioFinish"
+        @rename="onStudioRename"
         @roll="onStudioRoll"
       />
       <section v-else class="theme-editor-tokens" aria-label="Token editor">
         <p v-if="draft.recipe" class="theme-editor-studio-hint">
           <i class="fa-solid fa-circle-info" aria-hidden="true" />
-          This theme was built with Studio. Re-opening Studio and changing it overwrites manual token tweaks here.
+          This theme is a light + dark pair (one card in the picker). Visitors switch between them
+          with the site's Light/Dark toggle. Re-opening Studio and changing it overwrites manual
+          token tweaks here.
         </p>
         <AdminThemeTokenGroup
           v-for="group in TOKEN_GROUP_ORDER"
@@ -669,6 +719,35 @@ onBeforeUnmount(() => {
   color: var(--accent);
 }
 
+.theme-editor-export { position: relative; }
+.theme-editor-export > summary { list-style: none; cursor: pointer; }
+.theme-editor-export > summary::-webkit-details-marker { display: none; }
+.theme-editor-export-menu {
+  position: absolute;
+  right: 0;
+  top: calc(100% + 4px);
+  z-index: var(--z-dropdown);
+  display: flex;
+  flex-direction: column;
+  min-width: 220px;
+  background: var(--surface);
+  border: var(--border-width-default) solid var(--border);
+  box-shadow: var(--shadow-md);
+}
+.theme-editor-export-menu button {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-2) var(--space-3);
+  background: none;
+  border: 0;
+  text-align: left;
+  font-size: var(--text-sm);
+  color: var(--text);
+  cursor: pointer;
+}
+.theme-editor-export-menu button:hover { background: var(--surface2); }
+
 .theme-editor-error {
   margin: 0;
   padding: var(--space-3) var(--space-4);

package/pages/admin/theme/index.vue

@@ -37,6 +37,13 @@ const themesApi = useThemeAdmin();
 const router = useRouter();
 const { themeStudio } = useFeatures();
 
+/** The "New theme" dropdown (<details>); closed after a choice is picked. */
+const newMenu = ref<HTMLDetailsElement | null>(null);
+function pick(action: () => void): void {
+  newMenu.value?.removeAttribute('open');
+  action();
+}
+
 const { data: settings, refresh: refreshSettings } = await useFetch<Record<string, unknown>>('/api/admin/settings');
 
 const saving = ref(false);
@@ -168,11 +175,14 @@ function createBlank(): void {
   if (customId && themesApi.data.value) {
     const src = themesApi.data.value.custom.find((t) => t.id === customId);
     if (src) {
+      const copyId = nextAvailableId(`${src.id}-copy`);
       const seed = {
-        id: nextAvailableId(`${src.id}-copy`),
+        id: copyId,
         name: `${src.name} (copy)`,
         description: src.description ?? '',
-        family: 'custom',
+        // Unique family (= the slug) so each new theme is its OWN picker card
+        // instead of collapsing into a shared "custom" family.
+        family: copyId,
         isDark: src.isDark,
         parentTheme: src.parentTheme,
         tokens: { ...src.tokens },
@@ -188,11 +198,12 @@ function createBlank(): void {
   // so a complete capture is what keeps it from falling back to Classic).
   const detected = detectAppliedOverrides();
   const isBuiltInParent = themesApi.data.value?.builtIn.some((t) => t.id === active) ?? false;
+  const blankId = nextAvailableId('my-theme');
   const seed = {
-    id: nextAvailableId('my-theme'),
+    id: blankId,
     name: 'My theme',
     description: detected.count ? `Forked from the active theme (${detected.count} tokens).` : '',
-    family: 'custom',
+    family: blankId,
     isDark: detected.isDark,
     parentTheme: isBuiltInParent ? active : 'base',
     tokens: detected.tokens,
@@ -245,11 +256,12 @@ function captureCurrent(): void {
     notify('No custom tokens detected at :root', 'error');
     return;
   }
+  const capturedId = nextAvailableId(`captured-${new Date().toISOString().slice(0, 10)}`);
   const seed = {
-    id: nextAvailableId(`captured-${new Date().toISOString().slice(0, 10)}`),
+    id: capturedId,
     name: 'Captured current site theme',
     description: `Auto-captured from the live :root on ${new Date().toLocaleDateString()}, ${detected.count} tokens.`,
-    family: 'captured',
+    family: capturedId,
     isDark: detected.isDark,
     parentTheme: detected.isDark ? 'dark' : 'base',
     tokens: detected.tokens,
@@ -397,9 +409,6 @@ async function saveOverrides(overrides: Record<string, string>): Promise<void> {
         </p>
       </div>
       <div class="admin-theme-actions">
-        <button class="cpub-btn" :disabled="saving" @click="openImportDialog">
-          <i class="fa-solid fa-file-import" aria-hidden="true" /> Import…
-        </button>
         <input
           ref="importFileInput"
           type="file"
@@ -407,20 +416,36 @@ async function saveOverrides(overrides: Record<string, string>): Promise<void> {
           hidden
           @change="onImportFile"
         />
-        <template v-if="themeStudio">
-          <button class="cpub-btn" :disabled="saving" title="Roll a random theme" @click="startDice">
-            <i class="fa-solid fa-dice" aria-hidden="true" /> Surprise me
-          </button>
-          <button class="cpub-btn" :disabled="saving" @click="createBlank">
-            <i class="fa-solid fa-plus" aria-hidden="true" /> Blank
-          </button>
-          <button class="cpub-btn cpub-btn-primary" :disabled="saving" @click="startGuided">
-            <i class="fa-solid fa-wand-magic-sparkles" aria-hidden="true" /> Build with Studio
-          </button>
-        </template>
-        <button v-else class="cpub-btn cpub-btn-primary" :disabled="saving" @click="createBlank">
-          <i class="fa-solid fa-plus" aria-hidden="true" /> New custom theme
-        </button>
+        <!-- One clear entry point. Each option creates a SEPARATE theme (its own
+             family/card) — you can make as many as you like. -->
+        <details ref="newMenu" class="admin-theme-new">
+          <summary class="cpub-btn cpub-btn-primary">
+            <i class="fa-solid fa-plus" aria-hidden="true" /> New theme
+            <i class="fa-solid fa-chevron-down admin-theme-new-caret" aria-hidden="true" />
+          </summary>
+          <div class="admin-theme-new-menu" role="menu">
+            <button v-if="themeStudio" type="button" role="menuitem" @click="pick(startGuided)">
+              <i class="fa-solid fa-wand-magic-sparkles" aria-hidden="true" />
+              <span><b>Build with Studio</b><small>Guided: pick a vibe + colors, get a light/dark pair</small></span>
+            </button>
+            <button v-if="themeStudio" type="button" role="menuitem" @click="pick(startDice)">
+              <i class="fa-solid fa-dice" aria-hidden="true" />
+              <span><b>Surprise me</b><small>Roll a random coherent theme to start from</small></span>
+            </button>
+            <button type="button" role="menuitem" @click="pick(createBlank)">
+              <i class="fa-solid fa-plus" aria-hidden="true" />
+              <span><b>Blank</b><small>Fork the current look, edit tokens by hand</small></span>
+            </button>
+            <button v-if="discovery.count > 0" type="button" role="menuitem" @click="pick(captureCurrent)">
+              <i class="fa-solid fa-camera" aria-hidden="true" />
+              <span><b>Capture current</b><small>Save your layer app's CSS theme as editable</small></span>
+            </button>
+            <button type="button" role="menuitem" @click="pick(openImportDialog)">
+              <i class="fa-solid fa-file-import" aria-hidden="true" />
+              <span><b>Import</b><small>Load a .cpub-theme.json file</small></span>
+            </button>
+          </div>
+        </details>
       </div>
     </header>
 
@@ -496,6 +521,41 @@ async function saveOverrides(overrides: Record<string, string>): Promise<void> {
 .admin-page-desc { font-size: var(--text-sm); color: var(--text-dim); margin: 0; max-width: 560px; line-height: var(--leading-snug); }
 .admin-theme-actions { display: flex; gap: var(--space-2); margin-left: auto; }
 
+.admin-theme-new { position: relative; }
+.admin-theme-new > summary { list-style: none; cursor: pointer; }
+.admin-theme-new > summary::-webkit-details-marker { display: none; }
+.admin-theme-new-caret { font-size: 9px; margin-left: 2px; }
+.admin-theme-new-menu {
+  position: absolute;
+  right: 0;
+  top: calc(100% + 4px);
+  z-index: var(--z-dropdown);
+  display: flex;
+  flex-direction: column;
+  width: 300px;
+  max-width: 80vw;
+  background: var(--surface);
+  border: var(--border-width-default) solid var(--border);
+  box-shadow: var(--shadow-md);
+}
+.admin-theme-new-menu button {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--space-3);
+  padding: var(--space-3);
+  background: none;
+  border: 0;
+  border-bottom: var(--border-width-thin) solid var(--border2);
+  text-align: left;
+  color: var(--text);
+  cursor: pointer;
+}
+.admin-theme-new-menu button:last-child { border-bottom: 0; }
+.admin-theme-new-menu button:hover { background: var(--surface2); }
+.admin-theme-new-menu button > i { color: var(--accent); margin-top: 3px; width: 16px; text-align: center; }
+.admin-theme-new-menu button b { display: block; font-size: var(--text-sm); }
+.admin-theme-new-menu button small { display: block; font-size: var(--text-label); color: var(--text-dim); line-height: var(--leading-snug); margin-top: 2px; }
+
 .admin-theme-toast {
   position: fixed;
   top: calc(var(--nav-height) + var(--space-4));

package/plugins/theme.ts

@@ -11,6 +11,9 @@ export default defineNuxtPlugin(() => {
   const isDark = useState<boolean>('cpub-dark-mode', () => false);
   const themeInlineCss = useState<string>('cpub-theme-inline-css', () => '');
   const themeFontHref = useState<string>('cpub-theme-font-href', () => '');
+  // Light/dark attrs of a custom pair — lets the user toggle flip data-theme
+  // instantly client-side (both variants' tokens are injected below).
+  const themePair = useState<{ lightAttr: string; darkAttr: string } | null>('cpub-theme-pair', () => null);
 
   if (import.meta.server) {
     const event = useRequestEvent();
@@ -20,6 +23,7 @@ export default defineNuxtPlugin(() => {
       isDark.value = event.context.isDarkMode ?? false;
       themeInlineCss.value = event.context.themeInlineCss ?? '';
       themeFontHref.value = event.context.themeFontHref ?? '';
+      themePair.value = event.context.themePair ?? null;
     }
   }
 

package/server/middleware/theme.ts

@@ -16,6 +16,8 @@ declare module 'h3' {
     themeInlineCss: string;
     /** Google Fonts stylesheet URL for the active custom theme's fonts. Empty if none. */
     themeFontHref: string;
+    /** Light/dark data-theme attrs of a custom pair (for the client toggle). */
+    themePair: { lightAttr: string; darkAttr: string } | null;
   }
 }
 
@@ -40,14 +42,25 @@ export default defineEventHandler(async (event) => {
   event.context.resolvedTheme = ctx.resolvedTheme;
   event.context.isDarkMode = ctx.isDark;
 
-  // Build the inline style block. We scope tokens to `:root` so they
-  // override the loaded theme CSS but lose to inline element styles.
-  // Token overrides are added last (already merged into injectedTokens
-  // in resolveThemeContext) so they win.
-  event.context.themeInlineCss = Object.keys(ctx.injectedTokens).length > 0
-    ? tokensToCss(':root', ctx.injectedTokens)
-    : '';
+  // Build the inline style block.
+  //  - Custom theme(s): one block per variant, scoped to its `[data-theme]`
+  //    attr, with instance overrides merged in (so overrides win + apply in
+  //    every mode). A light/dark PAIR injects BOTH, so the client toggle can
+  //    flip `data-theme` and switch instantly — no server round-trip.
+  //  - Built-in / registered: only instance overrides at `:root` (their CSS
+  //    files already handle light/dark).
+  if (ctx.themeVariants.length > 0) {
+    event.context.themeInlineCss = ctx.themeVariants
+      .map((v) => tokensToCss(`:root[data-theme="${v.attr}"]`, { ...v.tokens, ...ctx.overrides }))
+      .filter(Boolean)
+      .join('\n');
+  } else {
+    event.context.themeInlineCss = Object.keys(ctx.overrides).length > 0
+      ? tokensToCss(':root', ctx.overrides)
+      : '';
+  }
 
   // Google Fonts for the active custom theme (CSP already allows googleapis).
   event.context.themeFontHref = ctx.fontHref;
+  event.context.themePair = ctx.pair;
 });

package/server/utils/instanceTheme.ts

@@ -104,9 +104,18 @@ export async function resolveThemeContext(
   instanceTheme: string;
   /** Whether the resolved theme is dark */
   isDark: boolean;
-  /** Token map to inject as inline :root style (custom theme tokens + overrides). Empty when not needed. */
-  injectedTokens: Record<string, string>;
-  /** Google Fonts stylesheet URL for the active custom theme's fonts. Empty when none. */
+  /**
+   * Custom-theme token blocks to inject, one per variant, each scoped to its
+   * own `[data-theme]` selector. For a light/dark PAIR this is BOTH variants,
+   * so the client can flip `data-theme` and switch instantly (no round-trip).
+   * Empty for built-in / registered themes (their CSS files handle modes).
+   */
+  themeVariants: Array<{ attr: string; tokens: Record<string, string> }>;
+  /** Instance-wide token overrides (apply in every mode). */
+  overrides: Record<string, string>;
+  /** Light/dark attrs of a custom pair, so the client toggle can flip instantly. */
+  pair: { lightAttr: string; darkAttr: string } | null;
+  /** Google Fonts stylesheet URL for the active custom theme(s) fonts. Empty when none. */
   fontHref: string;
 }> {
   const state = await getState();
@@ -114,61 +123,52 @@ export async function resolveThemeContext(
   // Validate the admin's choice — fall back to base if missing/unknown
   const admin = isKnownThemeId(state.defaultTheme, state, registeredIds) ? state.defaultTheme : 'base';
 
-  // Light/dark resolution. We only flip variants for built-in family pairs;
-  // custom themes use their declared pair if present, otherwise stay put.
+  const activeCustom = state.customByAttr.get(admin);
   let resolved = admin;
-  if (userScheme !== null) {
-    // Built-in family flip
-    if (VALID_THEME_IDS.has(admin)) {
+  let isDark = false;
+  let themeVariants: Array<{ attr: string; tokens: Record<string, string> }> = [];
+  let pair: { lightAttr: string; darkAttr: string } | null = null;
+  let fontHref = '';
+
+  if (activeCustom) {
+    // Gather the pair members (the default + its sibling, if both exist).
+    const members: Array<{ attr: string; rec: CustomThemeRecord }> = [{ attr: admin, rec: activeCustom }];
+    if (activeCustom.pairId) {
+      const sibAttr = `cpub-custom-${activeCustom.pairId}`;
+      const sib = state.customByAttr.get(sibAttr);
+      if (sib) members.push({ attr: sibAttr, rec: sib });
+    }
+    themeVariants = members.map((m) => ({ attr: m.attr, tokens: m.rec.tokens }));
+    const lightM = members.find((m) => !m.rec.isDark);
+    const darkM = members.find((m) => m.rec.isDark);
+    if (members.length === 2 && lightM && darkM) {
+      pair = { lightAttr: lightM.attr, darkAttr: darkM.attr };
+    }
+    // <html data-theme> = the variant matching the user's scheme (else the default).
+    if (userScheme === 'dark' && darkM) resolved = darkM.attr;
+    else if (userScheme === 'light' && lightM) resolved = lightM.attr;
+    else resolved = admin;
+    isDark = state.customByAttr.get(resolved)?.isDark ?? activeCustom.isDark;
+    // Load every variant's fonts so a client-side flip already has them.
+    const allFonts = [...new Set(members.flatMap((m) => m.rec.fonts ?? []))];
+    fontHref = allFonts.length ? googleHref(allFonts) : '';
+  } else {
+    // Built-in / registered: flip via the family's CSS variants on round-trip.
+    if (userScheme !== null && VALID_THEME_IDS.has(admin)) {
       const family = THEME_TO_FAMILY[admin] ?? 'classic';
       const variants = FAMILY_VARIANTS[family] ?? FAMILY_VARIANTS.classic!;
       resolved = userScheme === 'dark' ? variants.dark : variants.light;
-    } else {
-      // Custom theme — use pairId if defined
-      const custom = state.customByAttr.get(admin);
-      if (custom?.pairId) {
-        const pairAttr = `cpub-custom-${custom.pairId}`;
-        const pair = state.customByAttr.get(pairAttr);
-        if (pair && pair.isDark === (userScheme === 'dark')) {
-          resolved = pairAttr;
-        } else if (custom.isDark === (userScheme === 'dark')) {
-          resolved = admin;
-        }
-      }
-      // For registered themes (no pair info available server-side), we leave it alone
-      // — the layer-app author can declare a pair via the future RegisteredTheme.pairId
     }
-  }
-
-  // isDark detection
-  let isDark = false;
-  if (VALID_THEME_IDS.has(resolved)) {
     isDark = IS_DARK[resolved] ?? false;
-  } else {
-    const custom = state.customByAttr.get(resolved);
-    if (custom) isDark = custom.isDark;
   }
 
-  // Tokens to inject inline. Built-in themes don't need injection (their
-  // CSS files are already loaded). Custom themes always inject. Token
-  // overrides apply on top of whatever theme is active.
-  const injectedTokens: Record<string, string> = {};
-  const activeCustom = state.customByAttr.get(resolved);
-  if (activeCustom) {
-    Object.assign(injectedTokens, activeCustom.tokens);
-  }
-  // Instance overrides always last so they win
-  Object.assign(injectedTokens, state.tokenOverrides);
-
-  // Google Fonts for the active custom theme (theme-studio sets `fonts`).
-  const fontHref =
-    activeCustom?.fonts && activeCustom.fonts.length > 0 ? googleHref(activeCustom.fonts) : '';
-
   return {
     resolvedTheme: resolved,
     instanceTheme: admin,
     isDark,
-    injectedTokens,
+    themeVariants,
+    overrides: { ...state.tokenOverrides },
+    pair,
     fontHref,
   };
 }

package/theme/base.css

@@ -61,6 +61,16 @@
   --color-accent-bg: var(--accent-bg);
   --color-accent-border: var(--accent-border);
 
+  /* === SECONDARY ACCENT (violet) === */
+  --secondary: #8b5cf6;
+  --secondary-hover: #7c3aed;
+  --secondary-bg: rgba(139, 92, 246, 0.08);
+  --secondary-border: rgba(139, 92, 246, 0.25);
+  --color-on-secondary: #ffffff;
+
+  /* Film-grain overlay opacity (0 = off; app.vue mounts the overlay) */
+  --grain: 0;
+
   /* === SEMANTIC COLORS === */
   --green: #22c55e;
   --green-bg: rgba(34, 197, 94, 0.08);

package/theme/components.css

@@ -36,6 +36,15 @@
 
 .cpub-btn-primary:disabled { opacity: 0.5; cursor: not-allowed; }
 
+.cpub-btn-secondary {
+  background: var(--secondary);
+  color: var(--color-on-secondary);
+  border-color: var(--secondary);
+  box-shadow: 4px 4px 0 var(--border);
+}
+.cpub-btn-secondary:hover { background: var(--secondary-hover); box-shadow: 2px 2px 0 var(--border); }
+.cpub-btn-secondary:disabled { opacity: 0.5; cursor: not-allowed; }
+
 .cpub-btn-sm { padding: 4px 10px; font-size: 11px; min-height: 44px; }
 .cpub-btn-lg { padding: 12px 24px; font-size: 14px; font-weight: 600; }