From 0b1852ca9c1a4446205e577863196a8234764db1 Mon Sep 17 00:00:00 2001
From: James Morton <james.morton@quackback.io>
Date: Sat, 31 Oct 2026 06:51:30 +0000
Subject: [PATCH 1/2] feat(design): switch a portal with its own CSS, and back
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A portal with its own CSS stays on its old theme until someone switches.
Its old Settings › Portal page now offers the switch: today's portal beside
the portal switched, a report on the CSS, and Switch, held while the CSS
has refusals. History offers the way back.

The switch publishes today's branding converted, with the theme variables
the CSS sets on :root and .dark read in first, since the design sets those
variables itself and a tenant-layer :root would stop applying. The CSS
carries over unchanged without asking the plan, as it is the portal's
already. Switching back unpublishes the design, so the old theme, never
touched, shows again; the design's versions stay. Both are audited.

The switched frame is drawn by the engine on the server: with
?design=switch the bootstrap draws the portal switched, for a dashboard
session that can edit branding only.

The CSS check now offers the post-card part for .post-card.
---
 .../__tests__/appearance-view.test.tsx        |   6 +
 .../__tests__/design-switch.test.tsx          | 151 +++++++++
 .../appearance/design-switch-card.tsx         | 128 ++++++++
 .../settings/appearance/history-dialog.tsx    |  41 ++-
 .../settings/branding/portal-preview.tsx      |   5 +-
 .../settings/security/audit-log-page.tsx      |   2 +
 .../src/lib/client/queries/portal-design.ts   |  12 +-
 apps/web/src/lib/server/audit/log.ts          |   2 +
 .../domains/design/__tests__/css-lint.test.ts |  10 +
 .../design/__tests__/switch.db.test.ts        | 187 +++++++++++
 .../src/lib/server/domains/design/css-lint.ts |   3 +
 .../server/domains/design/design.actions.ts   |   4 +-
 .../server/domains/design/design.service.ts   |  67 ++++
 .../web/src/lib/server/domains/design/http.ts |   2 +
 .../src/lib/server/domains/design/switch.ts   | 201 ++++++++++++
 .../__tests__/bootstrap-client-safe.test.ts   |  91 ++++-
 .../web/src/lib/server/functions/bootstrap.ts | 310 ++++++++++--------
 .../src/lib/server/functions/portal-design.ts |  26 ++
 .../lib/server/policy/authz-matrix/MATRIX.md  |   7 +-
 .../shared/design/__tests__/convert.test.ts   |  35 +-
 apps/web/src/lib/shared/design/convert.ts     |  42 ++-
 apps/web/src/routes/__root.tsx                |  12 +-
 apps/web/src/routes/_portal.tsx               |   6 +-
 apps/web/src/routes/admin/settings.portal.tsx |  27 +-
 24 files changed, 1209 insertions(+), 168 deletions(-)
 create mode 100644 apps/web/src/components/admin/settings/appearance/__tests__/design-switch.test.tsx
 create mode 100644 apps/web/src/components/admin/settings/appearance/design-switch-card.tsx
 create mode 100644 apps/web/src/lib/server/domains/design/__tests__/switch.db.test.ts
 create mode 100644 apps/web/src/lib/server/domains/design/switch.ts

diff --git a/apps/web/src/components/admin/settings/appearance/__tests__/appearance-view.test.tsx b/apps/web/src/components/admin/settings/appearance/__tests__/appearance-view.test.tsx
index c88f7cab1a..33bc7991e1 100644
--- a/apps/web/src/components/admin/settings/appearance/__tests__/appearance-view.test.tsx
+++ b/apps/web/src/components/admin/settings/appearance/__tests__/appearance-view.test.tsx
@@ -56,6 +56,12 @@ vi.mock('@/lib/server/functions/portal-design', () => ({
     return { ok: true, revisionId: 'portal_design_revision_1', number: 1 }
   },
   restorePortalDesignVersionFn: async () => ({ ok: true }),
+  getPortalDesignSwitchFn: async () => ({
+    available: false,
+    canSwitchBack: false,
+    report: { errors: [], warnings: [], carried: [] },
+  }),
+  switchBackPortalDesignFn: async () => ({ ok: true }),
 }))
 
 vi.mock('@/lib/client/analytics', () => ({
diff --git a/apps/web/src/components/admin/settings/appearance/__tests__/design-switch.test.tsx b/apps/web/src/components/admin/settings/appearance/__tests__/design-switch.test.tsx
new file mode 100644
index 0000000000..112613a4fa
--- /dev/null
+++ b/apps/web/src/components/admin/settings/appearance/__tests__/design-switch.test.tsx
@@ -0,0 +1,151 @@
+// @vitest-environment happy-dom
+/**
+ * A portal with its own CSS is offered the switch on its old Settings › Portal
+ * page: the CSS report, today's portal beside the switched one, and Switch,
+ * held back while the CSS has refusals. Once switched, Versions offers the way
+ * back.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import type { ReactNode } from 'react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+const server = vi.hoisted(() => ({
+  invalidations: 0,
+  switches: 0,
+  switchesBack: 0,
+  outcome: { ok: true } as { ok: true } | { ok: false; code: string; message: string },
+}))
+
+vi.mock('@tanstack/react-router', () => ({
+  useRouter: () => ({
+    invalidate: async () => {
+      server.invalidations++
+    },
+  }),
+  ClientOnly: ({ children }: { children: ReactNode }) => <>{children}</>,
+}))
+vi.mock('@/components/admin/settings/branding/portal-preview', () => ({
+  PortalPreview: ({ switched }: { switched: boolean }) => (
+    <div data-testid="frame" data-switched={String(switched)} />
+  ),
+}))
+vi.mock('@/lib/server/functions/portal-design', () => ({
+  getPortalDesignSwitchFn: async () => null,
+  listPortalDesignVersionsFn: async () => [],
+  switchPortalDesignFn: async () => {
+    server.switches++
+    return server.outcome
+  },
+  switchBackPortalDesignFn: async () => {
+    server.switchesBack++
+    return server.outcome
+  },
+}))
+
+const { portalDesignQueries } = await import('@/lib/client/queries/portal-design')
+const { DesignSwitchCard } = await import('../design-switch-card')
+const { HistoryDialog } = await import('../history-dialog')
+
+const REPORT = {
+  errors: [] as Array<{ message: string; line?: number }>,
+  warnings: [{ message: '.portal-nav__item is internal and may change.', line: 3 }],
+  carried: [{ message: '--primary on :root becomes the accent.' }],
+}
+
+function withClient(ui: ReactNode, state: unknown) {
+  const client = new QueryClient({ defaultOptions: { queries: { staleTime: Infinity } } })
+  client.setQueryData(portalDesignQueries.switch().queryKey, state)
+  client.setQueryData(portalDesignQueries.versions().queryKey, [])
+  render(<QueryClientProvider client={client}>{ui}</QueryClientProvider>)
+}
+
+const card = <DesignSwitchCard workspaceName="Acme" faviconUrl={null} />
+
+afterEach(() => {
+  cleanup()
+  server.invalidations = 0
+  server.switches = 0
+  server.switchesBack = 0
+  server.outcome = { ok: true }
+})
+
+describe('the switch card', () => {
+  it('is absent when there is nothing to switch', () => {
+    withClient(card, { available: false, canSwitchBack: true, report: REPORT })
+    expect(screen.queryByRole('button', { name: 'Switch' })).toBeNull()
+  })
+
+  it('reports the CSS and compares today with the portal switched', () => {
+    withClient(card, { available: true, canSwitchBack: false, report: REPORT })
+    expect(screen.getByRole('list', { name: 'Moves into the design' }).textContent).toBe(
+      '--primary on :root becomes the accent.'
+    )
+    expect(screen.getByRole('list', { name: 'Check after switching' }).textContent).toBe(
+      'Line 3: .portal-nav__item is internal and may change.'
+    )
+    expect(screen.queryAllByTestId('frame')).toEqual([])
+    fireEvent.click(screen.getByRole('button', { name: 'Compare' }))
+    expect(screen.getAllByTestId('frame').map((frame) => frame.dataset.switched)).toEqual([
+      'false',
+      'true',
+    ])
+  })
+
+  it('switches and reloads the page as Appearance', async () => {
+    withClient(card, { available: true, canSwitchBack: false, report: REPORT })
+    await act(async () => fireEvent.click(screen.getByRole('button', { name: 'Switch' })))
+    expect(server.switches).toBe(1)
+    expect(server.invalidations).toBe(1)
+  })
+
+  it('holds the switch while the CSS has refusals, and shows a refusal', async () => {
+    withClient(card, {
+      available: true,
+      canSwitchBack: false,
+      report: { ...REPORT, errors: [{ message: '@import is not allowed.', line: 1 }] },
+    })
+    expect(
+      screen.getByRole('list', { name: 'Fix in Advanced CSS before switching' }).textContent
+    ).toBe('Line 1: @import is not allowed.')
+    expect(screen.getByRole('button', { name: 'Switch' }).hasAttribute('disabled')).toBe(true)
+
+    cleanup()
+    server.outcome = { ok: false, code: 'DESIGN_CHANGED', message: 'Already switched.' }
+    withClient(card, { available: true, canSwitchBack: false, report: REPORT })
+    await act(async () => fireEvent.click(screen.getByRole('button', { name: 'Switch' })))
+    expect(screen.getByRole('alert').textContent).toBe('Already switched.')
+    expect(server.invalidations).toBe(0)
+  })
+})
+
+describe('switching back', () => {
+  const dialog = (
+    <HistoryDialog
+      open
+      onOpenChange={() => {}}
+      currentNumber={1}
+      onRestore={async () => ({ ok: true })}
+    />
+  )
+
+  it('is offered once the portal has switched, and asks first', async () => {
+    withClient(dialog, { available: false, canSwitchBack: true, report: REPORT })
+    fireEvent.click(await screen.findByRole('button', { name: 'Switch back' }))
+    expect(server.switchesBack).toBe(0)
+    const confirm = await screen.findByRole('alertdialog')
+    await act(async () =>
+      fireEvent.click(
+        [...confirm.querySelectorAll('button')].find((b) => b.textContent === 'Switch back')!
+      )
+    )
+    expect(server.switchesBack).toBe(1)
+    await waitFor(() => expect(server.invalidations).toBe(1))
+  })
+
+  it('is not offered to a portal that never switched', async () => {
+    withClient(dialog, { available: false, canSwitchBack: false, report: REPORT })
+    await screen.findByRole('dialog')
+    expect(screen.queryByRole('button', { name: 'Switch back' })).toBeNull()
+  })
+})
diff --git a/apps/web/src/components/admin/settings/appearance/design-switch-card.tsx b/apps/web/src/components/admin/settings/appearance/design-switch-card.tsx
new file mode 100644
index 0000000000..541a74c618
--- /dev/null
+++ b/apps/web/src/components/admin/settings/appearance/design-switch-card.tsx
@@ -0,0 +1,128 @@
+import { useState } from 'react'
+import { useQuery, useQueryClient } from '@tanstack/react-query'
+import { ClientOnly, useRouter } from '@tanstack/react-router'
+import { Button } from '@/components/ui/button'
+import { PortalPreview } from '@/components/admin/settings/branding/portal-preview'
+import { portalDesignQueries } from '@/lib/client/queries/portal-design'
+import { switchPortalDesignFn } from '@/lib/server/functions/portal-design'
+import type { PortalPreviewDraft } from '@/components/public/preview-draft-context'
+
+interface Issue {
+  message: string
+  line?: number
+}
+
+const NO_DRAFT: PortalPreviewDraft = {}
+
+function Issues({ label, issues }: { label: string; issues: readonly Issue[] }) {
+  if (issues.length === 0) return null
+  return (
+    <div className="space-y-1">
+      <h3 className="text-xs font-medium">{label}</h3>
+      <ul aria-label={label} className="space-y-1 text-xs text-muted-foreground">
+        {issues.map((issue, index) => (
+          <li key={`${issue.line}-${index}`}>
+            {issue.line ? `Line ${issue.line}: ` : ''}
+            {issue.message}
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+
+/**
+ * A portal with its own CSS stays on its old theme until someone switches.
+ * The card compares the portal as it is with the portal switched, reports
+ * what becomes of the CSS, and switches. Refused CSS has to be fixed in
+ * Advanced CSS first.
+ */
+export function DesignSwitchCard({
+  workspaceName,
+  faviconUrl,
+}: {
+  workspaceName: string
+  faviconUrl: string | null
+}) {
+  const state = useQuery(portalDesignQueries.switch())
+  const router = useRouter()
+  const queryClient = useQueryClient()
+  const [comparing, setComparing] = useState(false)
+  const [switching, setSwitching] = useState(false)
+  const [refusal, setRefusal] = useState<string | null>(null)
+  if (!state.data?.available) return null
+  const { report } = state.data
+  const blocked = report.errors.length > 0
+
+  async function switchNow() {
+    setSwitching(true)
+    setRefusal(null)
+    const outcome = await switchPortalDesignFn()
+    if (outcome.ok) {
+      await queryClient.invalidateQueries({ queryKey: ['settings'] })
+      await router.invalidate()
+    } else {
+      setRefusal(outcome.message)
+    }
+    setSwitching(false)
+  }
+
+  const frame = (switched: boolean) => (
+    <ClientOnly>
+      <PortalPreview
+        theme="light"
+        refreshKey={switched ? 'switched' : 'today'}
+        draftCss=""
+        cssDirty={false}
+        draft={NO_DRAFT}
+        draftDirty={false}
+        viewport="desktop"
+        workspaceName={workspaceName}
+        faviconUrl={faviconUrl}
+        scaleToDesktop
+        switched={switched}
+      />
+    </ClientOnly>
+  )
+
+  return (
+    <section
+      aria-labelledby="design-switch-title"
+      className="space-y-4 rounded-lg border border-border/60 bg-card p-4"
+    >
+      <div className="flex flex-wrap items-center gap-3">
+        <p id="design-switch-title" className="min-w-0 flex-1 text-sm font-medium">
+          Your portal uses custom CSS. Switch to the new design system.
+        </p>
+        <Button variant="outline" size="sm" onClick={() => setComparing(!comparing)}>
+          {comparing ? 'Hide comparison' : 'Compare'}
+        </Button>
+        <Button size="sm" disabled={blocked || switching} onClick={() => void switchNow()}>
+          Switch
+        </Button>
+      </div>
+      {refusal && (
+        <p role="alert" className="text-[13px] text-destructive">
+          {refusal}
+        </p>
+      )}
+      <Issues label="Fix in Advanced CSS before switching" issues={report.errors} />
+      <Issues label="Moves into the design" issues={report.carried} />
+      <Issues label="Check after switching" issues={report.warnings} />
+      {comparing && (
+        <div className="grid grid-cols-1 gap-4 lg:grid-cols-2">
+          <figure className="min-w-0 space-y-2">
+            <figcaption className="text-xs font-medium text-muted-foreground">Today</figcaption>
+            {frame(false)}
+          </figure>
+          <figure className="min-w-0 space-y-2">
+            <figcaption className="text-xs font-medium text-muted-foreground">
+              After switching
+            </figcaption>
+            {frame(true)}
+          </figure>
+        </div>
+      )}
+    </section>
+  )
+}
diff --git a/apps/web/src/components/admin/settings/appearance/history-dialog.tsx b/apps/web/src/components/admin/settings/appearance/history-dialog.tsx
index ac18d17ab9..9dbe0a0b0c 100644
--- a/apps/web/src/components/admin/settings/appearance/history-dialog.tsx
+++ b/apps/web/src/components/admin/settings/appearance/history-dialog.tsx
@@ -1,5 +1,6 @@
 import { useState } from 'react'
-import { useQuery } from '@tanstack/react-query'
+import { useQuery, useQueryClient } from '@tanstack/react-query'
+import { useRouter } from '@tanstack/react-router'
 import type { PortalDesignRevisionId } from '@quackback/ids'
 import {
   AlertDialog,
@@ -21,6 +22,7 @@ import {
 } from '@/components/ui/dialog'
 import { TimeAgo } from '@/components/ui/time-ago'
 import { portalDesignQueries } from '@/lib/client/queries/portal-design'
+import { switchBackPortalDesignFn } from '@/lib/server/functions/portal-design'
 
 const SOURCE: Record<string, string> = {
   appearance: 'Appearance',
@@ -52,6 +54,20 @@ export function HistoryDialog({
     number: number
   } | null>(null)
   const [refusal, setRefusal] = useState<string | null>(null)
+  // A portal that switched from its old theme can go back to it.
+  const switched = useQuery({ ...portalDesignQueries.switch(), enabled: open })
+  const [confirmingBack, setConfirmingBack] = useState(false)
+  const router = useRouter()
+  const queryClient = useQueryClient()
+
+  async function switchBack() {
+    const outcome = await switchBackPortalDesignFn()
+    setConfirmingBack(false)
+    if (!outcome.ok) return setRefusal(outcome.message)
+    onOpenChange(false)
+    await queryClient.invalidateQueries({ queryKey: ['settings'] })
+    await router.invalidate()
+  }
 
   async function restore() {
     if (!confirming) return
@@ -104,6 +120,14 @@ export function HistoryDialog({
               </li>
             ))}
           </ul>
+          {switched.data?.canSwitchBack && (
+            <div className="flex items-center gap-3 text-[13px]">
+              <span className="flex-1 text-muted-foreground">Switched from the old theme.</span>
+              <Button variant="outline" size="sm" onClick={() => setConfirmingBack(true)}>
+                Switch back
+              </Button>
+            </div>
+          )}
           {refusal && (
             <p role="alert" className="text-[13px] text-destructive">
               {refusal}
@@ -125,6 +149,21 @@ export function HistoryDialog({
           </AlertDialogFooter>
         </AlertDialogContent>
       </AlertDialog>
+      <AlertDialog open={confirmingBack} onOpenChange={setConfirmingBack}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Switch back to the old theme?</AlertDialogTitle>
+            <AlertDialogDescription>
+              Visitors see the old theme and its CSS straight away. The design and its versions
+              stay.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>Cancel</AlertDialogCancel>
+            <AlertDialogAction onClick={switchBack}>Switch back</AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
     </>
   )
 }
diff --git a/apps/web/src/components/admin/settings/branding/portal-preview.tsx b/apps/web/src/components/admin/settings/branding/portal-preview.tsx
index cfa0c13598..ba89709927 100644
--- a/apps/web/src/components/admin/settings/branding/portal-preview.tsx
+++ b/apps/web/src/components/admin/settings/branding/portal-preview.tsx
@@ -48,6 +48,8 @@ interface PortalPreviewProps {
   } | null
   /** The page the frame shows: the root, Home or the feed at its own address. */
   page?: PreviewPage
+  /** Draw the portal as it would be after switching to the design. */
+  switched?: boolean
 }
 
 export type PreviewPage = 'root' | 'home' | 'feedback'
@@ -90,6 +92,7 @@ export function PortalPreview({
   scaleToDesktop = false,
   sort = 'trending',
   page = 'root',
+  switched = false,
 }: PortalPreviewProps) {
   const frameBox = useRef<HTMLDivElement>(null)
   const [boxWidth, setBoxWidth] = useState(0)
@@ -189,7 +192,7 @@ export function PortalPreview({
         <iframe
           key={refreshKey}
           ref={iframeRef}
-          src={portalPreviewSrc(theme, sort, page)}
+          src={`${portalPreviewSrc(theme, sort, page)}${switched ? '&design=switch' : ''}`}
           title="Portal preview"
           className="w-full border-0 bg-background"
           style={
diff --git a/apps/web/src/components/admin/settings/security/audit-log-page.tsx b/apps/web/src/components/admin/settings/security/audit-log-page.tsx
index f6f4c42dc4..ff009bb837 100644
--- a/apps/web/src/components/admin/settings/security/audit-log-page.tsx
+++ b/apps/web/src/components/admin/settings/security/audit-log-page.tsx
@@ -95,6 +95,8 @@ const FILTER_EVENT_TYPES: FilterEventOption[] = [
   { group: 'Settings', label: 'Custom CSS changed', value: 'branding.css.changed' },
   { group: 'Settings', label: 'Design published', value: 'design.published' },
   { group: 'Settings', label: 'Design restored', value: 'design.restored' },
+  { group: 'Settings', label: 'Switched to the design', value: 'design.switched' },
+  { group: 'Settings', label: 'Switched back to the old theme', value: 'design.switched_back' },
   { group: 'Settings', label: 'Settings applied', value: 'settings.applied' },
   { group: 'Settings', label: 'Settings undone', value: 'settings.undone' },
   { group: 'Portal', label: 'Widget sign-in changed', value: 'portal.widget_signin.changed' },
diff --git a/apps/web/src/lib/client/queries/portal-design.ts b/apps/web/src/lib/client/queries/portal-design.ts
index a3399a87d3..b26eea53a5 100644
--- a/apps/web/src/lib/client/queries/portal-design.ts
+++ b/apps/web/src/lib/client/queries/portal-design.ts
@@ -1,5 +1,9 @@
 import { queryOptions } from '@tanstack/react-query'
-import { getPortalDesignFn, listPortalDesignVersionsFn } from '@/lib/server/functions/portal-design'
+import {
+  getPortalDesignFn,
+  getPortalDesignSwitchFn,
+  listPortalDesignVersionsFn,
+} from '@/lib/server/functions/portal-design'
 import { getPortalDesignAiStatusFn } from '@/lib/server/functions/portal-design-ai'
 
 export const portalDesignQueries = {
@@ -16,6 +20,12 @@ export const portalDesignQueries = {
       queryFn: () => getPortalDesignAiStatusFn(),
       staleTime: 5 * 60_000,
     }),
+  /** Whether a portal with its own CSS can switch to the design, or back, and its CSS report. */
+  switch: () =>
+    queryOptions({
+      queryKey: ['settings', 'portal-design', 'switch'],
+      queryFn: () => getPortalDesignSwitchFn(),
+    }),
   /** Published versions, newest first. */
   versions: () =>
     queryOptions({
diff --git a/apps/web/src/lib/server/audit/log.ts b/apps/web/src/lib/server/audit/log.ts
index df268d5d1b..9617841f71 100644
--- a/apps/web/src/lib/server/audit/log.ts
+++ b/apps/web/src/lib/server/audit/log.ts
@@ -50,6 +50,8 @@ export type AuditEventType =
   | 'branding.theme.changed'
   | 'design.published'
   | 'design.restored'
+  | 'design.switched'
+  | 'design.switched_back'
   | 'branding.css.changed'
   | 'branding.website.applied'
   | 'branding.website.undone'
diff --git a/apps/web/src/lib/server/domains/design/__tests__/css-lint.test.ts b/apps/web/src/lib/server/domains/design/__tests__/css-lint.test.ts
index 5403680c86..52167b1c07 100644
--- a/apps/web/src/lib/server/domains/design/__tests__/css-lint.test.ts
+++ b/apps/web/src/lib/server/domains/design/__tests__/css-lint.test.ts
@@ -55,6 +55,16 @@ describe('lintDesignCss', () => {
     ])
   })
 
+  it('offers the part only for a class that is the whole part', () => {
+    const { warnings } = lintDesignCss(
+      '.post-card { border-width: 2px; } .post-card__link { color: red; }'
+    )
+    expect(warnings.map((warning) => warning.fix ?? null)).toEqual([
+      { find: '.post-card', replace: '[data-qb-part="post-card"]' },
+      null,
+    ])
+  })
+
   it('warns on !important, a private token, an unknown part and poor contrast', () => {
     const { errors, warnings } = lintDesignCss(`
       [data-qb-part="header"] { color: #999999 !important; background: #ffffff; }
diff --git a/apps/web/src/lib/server/domains/design/__tests__/switch.db.test.ts b/apps/web/src/lib/server/domains/design/__tests__/switch.db.test.ts
new file mode 100644
index 0000000000..45704b3613
--- /dev/null
+++ b/apps/web/src/lib/server/domains/design/__tests__/switch.db.test.ts
@@ -0,0 +1,187 @@
+/**
+ * A portal with its own CSS stays on its old theme until a person switches.
+ * The switch publishes its branding converted, the theme variables its CSS
+ * sets read in first, with the CSS carried over; switching back shows the old
+ * theme again, untouched, and the switch can be made again.
+ */
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createId, type PrincipalId, type UserId } from '@quackback/ids'
+import { createDbTestFixture, testDb } from '@/lib/server/__tests__/db-test-fixture'
+import { auditLog, eq, principal, settings, user } from '@/lib/server/db'
+
+vi.mock('@/lib/server/db', async (original) => ({
+  ...(await original<typeof import('@/lib/server/db')>()),
+  db: (await import('@/lib/server/__tests__/db-test-fixture')).testDb,
+}))
+vi.mock('@/lib/server/cache', async (original) => ({
+  ...(await original<typeof import('@/lib/server/cache')>()),
+  cacheGet: vi.fn(async () => null),
+  cacheSet: vi.fn(async () => undefined),
+  cacheDel: vi.fn(async () => undefined),
+}))
+vi.mock('@/lib/server/local-cache', async (original) => ({
+  ...(await original<typeof import('@/lib/server/local-cache')>()),
+  localCacheGet: () => undefined,
+  localCacheSet: () => undefined,
+}))
+// The CSS is the portal's already, so the switch never asks the plan.
+vi.mock('@/lib/server/domains/settings/tier-enforce', async () => {
+  const { TierLimitError } = await import('@/lib/server/errors/tier-limit-error')
+  return {
+    assertTierFeature: async () => {
+      throw new TierLimitError({ limit: 'features.customCss', message: 'Not on this plan.' })
+    },
+  }
+})
+
+const { getWorkspaceSettings } = await import('@/lib/server/domains/settings/settings.service')
+const { readDesignSwitch, switchBackFromDesign, switchPreviewView, switchToDesign } =
+  await import('../switch')
+const { config, resetConfig } = await import('@/lib/server/config')
+
+const fixture = await createDbTestFixture()
+let saved: NodeJS.ProcessEnv
+beforeEach(async () => {
+  expect(fixture.available).toBe(true)
+  saved = { ...process.env }
+  Object.assign(process.env, { BASE_URL: 'https://portal.example.com', SECRET_KEY: 'x'.repeat(48) })
+  resetConfig()
+  await fixture.begin()
+  await testDb.delete(settings)
+})
+afterEach(async () => {
+  process.env = saved
+  resetConfig()
+  await fixture.rollback()
+})
+afterAll(fixture.close)
+
+const CSS = [
+  ':root { --primary: #0f766e; --ring: #111111; --brand-stripe: #ff0000; }',
+  '.dark { --primary: #5eead4; }',
+  '.portal-nav__item { font-weight: 700; }',
+].join('\n')
+
+async function workspace(
+  customCss: string,
+  flags: Record<string, boolean> = { portalDesignV2: true }
+) {
+  await testDb.insert(settings).values({
+    id: createId('workspace'),
+    name: 'Acme',
+    slug: `acme-${createId('workspace').slice(-8)}`,
+    createdAt: new Date(),
+    featureFlags: JSON.stringify(flags),
+    brandingConfig: JSON.stringify({ themeMode: 'light', light: { primary: '#7a1f35' } }),
+    customCss,
+    setupState: JSON.stringify({ version: 2, steps: { core: true, workspace: true }, goals: [] }),
+  })
+}
+
+async function author() {
+  const userId = createId('user') as UserId
+  const principalId = createId('principal') as PrincipalId
+  await testDb.insert(user).values({ id: userId, name: 'Admin', email: `${userId}@example.com` })
+  await testDb
+    .insert(principal)
+    .values({ id: principalId, userId, role: 'admin', type: 'user', createdAt: new Date() })
+  return {
+    principalId,
+    actor: { userId, email: `${userId}@example.com`, role: 'admin', type: 'user' as const },
+  }
+}
+
+const engine = async () => (await getWorkspaceSettings())?.portalDesign
+
+describe('switching a portal with its own CSS', () => {
+  it('reports what becomes of the CSS before switching', async () => {
+    await workspace(CSS)
+    const state = await readDesignSwitch()
+    expect(state).toMatchObject({ available: true, canSwitchBack: false })
+    expect(state.report.errors).toEqual([])
+    expect(state.report.carried.map((issue) => issue.message)).toEqual([
+      '--primary on :root becomes the accent.',
+      '--primary on .dark becomes the dark accent.',
+    ])
+    const warnings = state.report.warnings.map((issue) => issue.message)
+    expect(warnings).toContainEqual(expect.stringMatching(/^--ring on :root stops applying/))
+    expect(warnings).toContainEqual(expect.stringMatching(/^\.portal-nav__item is internal/))
+    expect(warnings.join('\n')).not.toContain('--brand-stripe')
+  })
+
+  it('draws the switched portal for the preview, and only before switching', async () => {
+    await workspace(CSS)
+    expect(await engine()).toBeUndefined()
+    const view = await switchPreviewView()
+    expect(view?.engine === 'v2' && view.themeStyles).toContain('--qb-accent: #0f766e;')
+    expect(view?.engine === 'v2' && view.customCss).toContain('.portal-nav__item')
+    await switchToDesign(await author())
+    expect(await switchPreviewView()).toBeNull()
+  })
+
+  it('publishes the converted design with the CSS, without asking the plan', async () => {
+    await workspace(CSS)
+    const who = await author()
+    expect(await switchToDesign(who)).toEqual({ ok: true, number: 1 })
+    const view = await engine()
+    expect(view).toMatchObject({ engine: 'v2', revision: 1 })
+    expect(view?.engine === 'v2' && view.themeStyles).toContain('--qb-accent: #0f766e;')
+    expect(view?.engine === 'v2' && view.customCss).toBe(`@layer tenant {\n${CSS}\n}`)
+    expect(await readDesignSwitch()).toMatchObject({ available: false, canSwitchBack: true })
+    expect(await switchToDesign(who)).toMatchObject({ ok: false, code: 'DESIGN_CHANGED' })
+  })
+
+  it('switches back to the old theme, untouched, and can switch again', async () => {
+    await workspace(CSS)
+    const who = await author()
+    await switchToDesign(who)
+    expect(await switchBackFromDesign(who)).toEqual({ ok: true })
+    expect(await engine()).toBeUndefined()
+    const after = await getWorkspaceSettings()
+    expect(after?.customCss).toBe(CSS)
+    expect(after?.brandingConfig).toEqual({ themeMode: 'light', light: { primary: '#7a1f35' } })
+    expect(await readDesignSwitch()).toMatchObject({ available: true })
+    expect(await switchToDesign(who)).toEqual({ ok: true, number: 2 })
+
+    const rows = await testDb
+      .select()
+      .from(auditLog)
+      .where(eq(auditLog.actorUserId, who.actor.userId))
+    expect(rows.map((row) => row.eventType).sort()).toEqual([
+      'design.switched',
+      'design.switched',
+      'design.switched_back',
+    ])
+  })
+
+  it('refuses CSS that reaches past styling, until it is fixed', async () => {
+    await workspace('@import url(https://example.com/x.css);\nbody { color: red; }')
+    const state = await readDesignSwitch()
+    expect(state.available).toBe(true)
+    expect(state.report.errors.map((issue) => issue.message)).toEqual([
+      '@import is not allowed: put the CSS here instead.',
+    ])
+    expect(await switchToDesign(await author())).toMatchObject({ ok: false, code: 'INVALID_CSS' })
+    expect(await engine()).toBeUndefined()
+  })
+
+  it('has nothing to switch without CSS, without the flag, or held on the old theme', async () => {
+    const who = await author()
+    await workspace('/* nothing yet */')
+    expect(await readDesignSwitch()).toMatchObject({ available: false, canSwitchBack: false })
+    expect(await switchToDesign(who)).toMatchObject({ ok: false, code: 'NOT_SWITCHABLE' })
+    expect(await switchBackFromDesign(who)).toMatchObject({ ok: false, code: 'NOT_SWITCHED' })
+
+    await testDb.delete(settings)
+    await workspace(CSS, {})
+    expect(await readDesignSwitch()).toMatchObject({ available: false })
+
+    await testDb.delete(settings)
+    await workspace(CSS)
+    process.env.PORTAL_DESIGN_ENGINE = 'legacy'
+    resetConfig()
+    expect(config.portalDesignEngine).toBe('legacy')
+    expect(await readDesignSwitch()).toMatchObject({ available: false })
+    expect(await switchToDesign(who)).toMatchObject({ ok: false, code: 'NOT_SWITCHABLE' })
+  })
+})
diff --git a/apps/web/src/lib/server/domains/design/css-lint.ts b/apps/web/src/lib/server/domains/design/css-lint.ts
index 193a8721dc..74e5210b8e 100644
--- a/apps/web/src/lib/server/domains/design/css-lint.ts
+++ b/apps/web/src/lib/server/domains/design/css-lint.ts
@@ -45,6 +45,7 @@ const INTERNAL_CLASSES: Record<string, string> = {
   'portal-nav__item': '[data-qb-part="nav-item"]',
   'portal-nav__item--active': '[data-qb-part="nav-item"][data-state="active"]',
   'portal-band': '[data-qb-part="band"]',
+  'post-card': '[data-qb-part="post-card"]',
   'post-card__vote--voted': '[data-qb-part="vote-button"][data-state="voted"]',
 }
 
@@ -91,6 +92,8 @@ export function lintDesignCss(css: string): CssLintReport {
           message: '@import is not allowed: put the CSS here instead.',
           line: lineOf(node),
         })
+        // Its url() is the same refusal.
+        return csstree.walk.skip
       }
       if (node.type === 'Url' && !OWN_STORAGE.test(node.value.trim())) {
         errors.push({
diff --git a/apps/web/src/lib/server/domains/design/design.actions.ts b/apps/web/src/lib/server/domains/design/design.actions.ts
index bf26ef5e12..89f6b15b87 100644
--- a/apps/web/src/lib/server/domains/design/design.actions.ts
+++ b/apps/web/src/lib/server/domains/design/design.actions.ts
@@ -34,6 +34,8 @@ const REFUSAL_CODES = [
   'DRAFT_CHANGED',
   'INVALID_CSS',
   'TIER_LIMIT_EXCEEDED',
+  'NOT_SWITCHABLE',
+  'NOT_SWITCHED',
 ] as const
 export type DesignRefusalCode = (typeof REFUSAL_CODES)[number]
 export type DesignRefusal = { ok: false; code: DesignRefusalCode; message: string }
@@ -63,7 +65,7 @@ function reportOf(doc: PortalDesign): DesignReport {
 }
 
 /** Runs a write, turning a refusal a person can act on into a value. */
-async function refusable<T>(write: () => Promise<T>): Promise<T | DesignRefusal> {
+export async function refusable<T>(write: () => Promise<T>): Promise<T | DesignRefusal> {
   try {
     return await write()
   } catch (error) {
diff --git a/apps/web/src/lib/server/domains/design/design.service.ts b/apps/web/src/lib/server/domains/design/design.service.ts
index 67dafbdd1d..ed003a88e7 100644
--- a/apps/web/src/lib/server/domains/design/design.service.ts
+++ b/apps/web/src/lib/server/domains/design/design.service.ts
@@ -314,6 +314,73 @@ export async function publishStartingDesign(
   return true
 }
 
+/**
+ * Publishes a workspace's design for the first time, from its own theme and
+ * CSS, at a person's request. Refused once a design is published.
+ */
+export async function publishSwitchedDesign(
+  document: PortalDesign,
+  author: DesignAuthor
+): Promise<{ revisionId: PortalDesignRevisionId; number: number }> {
+  const valid = validateDesign(document)
+  const result = await db.transaction(async (tx) => {
+    await tx.insert(portalDesigns).values({}).onConflictDoNothing()
+    const row = (await designRow(tx, true))!
+    if (row.publishedRevisionId) {
+      throw new ConflictError('DESIGN_CHANGED', 'This portal already uses the design system.')
+    }
+    const published = await publishDocument(
+      tx,
+      row.id,
+      valid,
+      author,
+      'conversion',
+      'Switched from custom CSS'
+    )
+    await recordAuditEventInTransaction(tx, {
+      event: 'design.switched',
+      actor: author.actor,
+      headers: author.headers,
+      target: { type: 'portal_design', id: row.id },
+      after: { revision: published.number },
+      metadata: { principalId: author.principalId, revisionId: published.revisionId },
+    })
+    return published
+  })
+  await invalidateSettingsCache()
+  return result
+}
+
+/**
+ * Takes the published design off the portal, so the old theme shows again.
+ * Its versions and any draft stay, ready to publish again.
+ */
+export async function unpublishDesign(author: DesignAuthor): Promise<void> {
+  await db.transaction(async (tx) => {
+    const row = await designRow(tx, true)
+    if (!row?.publishedRevisionId) {
+      throw new ConflictError(
+        'NOT_SWITCHED',
+        'This portal has no published design to switch back from.'
+      )
+    }
+    const published = await revision(tx, row.publishedRevisionId)
+    await tx
+      .update(portalDesigns)
+      .set({ publishedRevisionId: null, updatedAt: new Date() })
+      .where(eq(portalDesigns.id, row.id))
+    await recordAuditEventInTransaction(tx, {
+      event: 'design.switched_back',
+      actor: author.actor,
+      headers: author.headers,
+      target: { type: 'portal_design', id: row.id },
+      before: { revision: published?.number ?? null },
+      metadata: { principalId: author.principalId },
+    })
+  })
+  await invalidateSettingsCache()
+}
+
 /** Publishes an old revision's document as the next revision. A draft in progress is kept. */
 export async function restoreRevision(
   revisionId: PortalDesignRevisionId,
diff --git a/apps/web/src/lib/server/domains/design/http.ts b/apps/web/src/lib/server/domains/design/http.ts
index 5084e295f7..386a4e790a 100644
--- a/apps/web/src/lib/server/domains/design/http.ts
+++ b/apps/web/src/lib/server/domains/design/http.ts
@@ -24,6 +24,8 @@ const REFUSAL_STATUS: Record<DesignRefusalCode, number> = {
   REVISION_NOT_FOUND: 404,
   INVALID_CSS: 400,
   TIER_LIMIT_EXCEEDED: 403,
+  NOT_SWITCHABLE: 409,
+  NOT_SWITCHED: 409,
 }
 
 /** The key needs the settings scope and its owner the branding permission. */
diff --git a/apps/web/src/lib/server/domains/design/switch.ts b/apps/web/src/lib/server/domains/design/switch.ts
new file mode 100644
index 0000000000..da138b887a
--- /dev/null
+++ b/apps/web/src/lib/server/domains/design/switch.ts
@@ -0,0 +1,201 @@
+/**
+ * Moving a portal with its own CSS onto the design engine, and back.
+ *
+ * Such a portal stays on its old theme until a person switches. The switch
+ * publishes today's branding converted, with the portal's CSS carried over
+ * unchanged into the design's CSS, where it renders in the tenant layer. The
+ * design sets the portal's theme variables itself, so the ones the CSS sets on
+ * `:root` and `.dark` are read into the branding first and become design
+ * fields where the converter has one. The old theme's settings stay untouched,
+ * so switching back takes the design off the portal and the old theme shows as
+ * it did.
+ */
+import { config } from '@/lib/server/config'
+import { getWorkspaceSettings } from '@/lib/server/domains/settings/settings.service'
+import {
+  CARRIED_THEME_VARIABLES,
+  carriesThemeVariable,
+  convertLegacyBranding,
+} from '@/lib/shared/design/convert'
+import type { PortalDesign } from '@/lib/shared/design/schema'
+import type { PortalDesignView } from '@/lib/shared/design/view'
+import { extractCssVariables } from '@/lib/shared/theme/css-parser'
+import type { ThemeVariables } from '@/lib/shared/theme/types'
+import { lintDesignCss, type CssIssue } from './css-lint'
+import { refusable, type DesignRefusal } from './design.actions'
+import {
+  getDesignState,
+  publishSwitchedDesign,
+  unpublishDesign,
+  type DesignAuthor,
+} from './design.service'
+import { advancedCssRemainder, legacyBrandingOf, portalDesignView } from './engine'
+
+export interface DesignSwitchReport {
+  /** Refused CSS, which blocks the switch until it is fixed. */
+  errors: CssIssue[]
+  /** CSS that still works after switching but may break later, or stops applying. */
+  warnings: CssIssue[]
+  /** Theme variables the CSS sets that become design fields. */
+  carried: CssIssue[]
+}
+
+export interface DesignSwitch {
+  /** The portal can switch: the engine is on, it has CSS of its own and no published design. */
+  available: boolean
+  /** It switched and can go back: a design is published over CSS the old theme kept. */
+  canSwitchBack: boolean
+  report: DesignSwitchReport
+}
+
+/** Every theme variable, by its name in the theme settings. */
+const THEME_VARIABLES = new Set<string>(
+  Object.keys({
+    background: 1,
+    foreground: 1,
+    card: 1,
+    cardForeground: 1,
+    popover: 1,
+    popoverForeground: 1,
+    primary: 1,
+    primaryForeground: 1,
+    secondary: 1,
+    secondaryForeground: 1,
+    muted: 1,
+    mutedForeground: 1,
+    accent: 1,
+    accentForeground: 1,
+    accentInk: 1,
+    destructive: 1,
+    destructiveForeground: 1,
+    border: 1,
+    input: 1,
+    ring: 1,
+    success: 1,
+    chart1: 1,
+    chart2: 1,
+    chart3: 1,
+    chart4: 1,
+    chart5: 1,
+    fontSans: 1,
+    radius: 1,
+    shadow2xs: 1,
+    shadowXs: 1,
+    shadowSm: 1,
+    shadow: 1,
+    shadowMd: 1,
+    shadowLg: 1,
+    shadowXl: 1,
+    shadow2xl: 1,
+  } satisfies Record<keyof ThemeVariables, 1>)
+)
+
+/** `--muted-foreground` as `mutedForeground`, if it is a theme variable. */
+function themeVariable(property: string): keyof ThemeVariables | null {
+  const name = property.slice(2).replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase())
+  return THEME_VARIABLES.has(name) ? (name as keyof ThemeVariables) : null
+}
+
+/** The theme variables the CSS sets, per mode, with what becomes of each. */
+function cssThemeVariables(css: string) {
+  const found = extractCssVariables(css)
+  const vars = { light: {} as ThemeVariables, dark: {} as ThemeVariables }
+  const carried: CssIssue[] = []
+  const lost: CssIssue[] = []
+  for (const mode of ['light', 'dark'] as const) {
+    const where = mode === 'light' ? ':root' : '.dark'
+    for (const [property, value] of Object.entries(found[mode])) {
+      const name = themeVariable(property)
+      if (!name) continue
+      vars[mode][name] = value
+      if (carriesThemeVariable(name, value, mode)) {
+        const field = CARRIED_THEME_VARIABLES[name as keyof typeof CARRIED_THEME_VARIABLES]
+        carried.push({
+          message: `${property} on ${where} becomes the ${mode === 'dark' ? 'dark ' : ''}${field}.`,
+        })
+      } else {
+        lost.push({
+          message: `${property} on ${where} stops applying: the design sets the portal's theme. Set it in Brand.`,
+        })
+      }
+    }
+  }
+  return { vars, carried, lost }
+}
+
+interface Switched {
+  design: PortalDesign
+  report: DesignSwitchReport
+}
+
+/** What the portal would switch to, or null if it has no CSS of its own or the engine is off. */
+async function switchedDesign(): Promise<Switched | null> {
+  if (config.portalDesignEngine === 'legacy') return null
+  const settings = await getWorkspaceSettings()
+  const css = settings?.customCss?.trim() ?? ''
+  if (!settings?.featureFlags?.portalDesignV2 || advancedCssRemainder(css) === '') return null
+  const { vars, carried, lost } = cssThemeVariables(css)
+  const branding = settings.brandingConfig ?? {}
+  const design = convertLegacyBranding(
+    legacyBrandingOf({
+      ...settings.settings,
+      brandingConfig: {
+        ...branding,
+        light: { ...branding.light, ...vars.light },
+        dark: { ...branding.dark, ...vars.dark },
+      },
+      portalConfig: settings.portalConfig,
+      customCss: css,
+    })
+  )
+  design.css = css
+  const lint = lintDesignCss(css)
+  return { design, report: { errors: lint.errors, warnings: [...lost, ...lint.warnings], carried } }
+}
+
+const NONE: DesignSwitchReport = { errors: [], warnings: [], carried: [] }
+
+export async function readDesignSwitch(): Promise<DesignSwitch> {
+  const [switched, state] = await Promise.all([switchedDesign(), getDesignState()])
+  if (!switched) return { available: false, canSwitchBack: false, report: NONE }
+  if (state?.published) return { available: false, canSwitchBack: true, report: NONE }
+  return { available: true, canSwitchBack: false, report: switched.report }
+}
+
+/**
+ * The portal as it would look switched, for the preview frame beside today's.
+ * Null once a design is published, or when there is nothing to switch.
+ */
+export async function switchPreviewView(): Promise<PortalDesignView | null> {
+  const [switched, state] = await Promise.all([switchedDesign(), getDesignState()])
+  if (!switched || state?.published) return null
+  return portalDesignView({ engine: 'v2', doc: switched.design, revision: null })
+}
+
+/** Switches the portal to the design, its CSS carried over. Refused CSS is refused here too. */
+export async function switchToDesign(
+  author: DesignAuthor
+): Promise<{ ok: true; number: number } | DesignRefusal> {
+  return refusable(async () => {
+    const switched = await switchedDesign()
+    if (!switched) {
+      return {
+        ok: false as const,
+        code: 'NOT_SWITCHABLE' as const,
+        message: 'This portal has no custom CSS to switch from.',
+      }
+    }
+    const { number } = await publishSwitchedDesign(switched.design, author)
+    return { ok: true as const, number }
+  })
+}
+
+/** Takes the design off the portal, so its old theme and CSS show again. */
+export async function switchBackFromDesign(
+  author: DesignAuthor
+): Promise<{ ok: true } | DesignRefusal> {
+  return refusable(async () => {
+    await unpublishDesign(author)
+    return { ok: true as const }
+  })
+}
diff --git a/apps/web/src/lib/server/functions/__tests__/bootstrap-client-safe.test.ts b/apps/web/src/lib/server/functions/__tests__/bootstrap-client-safe.test.ts
index 57332fba25..a05d071065 100644
--- a/apps/web/src/lib/server/functions/__tests__/bootstrap-client-safe.test.ts
+++ b/apps/web/src/lib/server/functions/__tests__/bootstrap-client-safe.test.ts
@@ -10,17 +10,33 @@ import { describe, it, expect, vi, beforeEach } from 'vitest'
 
 const hoisted = vi.hoisted(() => ({
   getWorkspaceSettings: vi.fn(),
-  handlers: [] as Array<() => Promise<unknown>>,
+  getOptionalAuth: vi.fn(),
+  switchPreviewView: vi.fn(),
+  handlers: [] as Array<(input: { data: unknown }) => Promise<unknown>>,
+  validate: (data: unknown) => data,
 }))
 
 vi.mock('@tanstack/react-start', () => ({
   createServerOnlyFn: <T>(fn: T) => fn,
-  createServerFn: () => ({
-    handler(fn: () => Promise<unknown>) {
-      hoisted.handlers.push(fn)
-      return fn
-    },
-  }),
+  createServerFn: () => {
+    const builder = {
+      validator(validate: (data: unknown) => unknown) {
+        hoisted.validate = validate
+        return builder
+      },
+      handler(fn: (input: { data: unknown }) => Promise<unknown>) {
+        hoisted.handlers.push(fn)
+        return fn
+      },
+    }
+    return builder
+  },
+}))
+vi.mock('@/lib/server/functions/auth-helpers', () => ({
+  getOptionalAuth: hoisted.getOptionalAuth,
+}))
+vi.mock('@/lib/server/domains/design/switch', () => ({
+  switchPreviewView: hoisted.switchPreviewView,
 }))
 vi.mock('@tanstack/react-start/server', () => ({
   getRequestHeaders: () => new Headers({ host: 'feedback.example' }),
@@ -97,10 +113,15 @@ function workspaceSettings(rawSetupState: string) {
   }
 }
 
-async function getBootstrapData() {
+async function getBootstrapData(input?: unknown) {
   if (hoisted.handlers.length === 0) await import('../bootstrap')
-  return (await hoisted.handlers[0]!()) as {
-    settings: { name: string; settings: object; statusConfig: object } | null
+  return (await hoisted.handlers[0]!({ data: hoisted.validate(input) })) as {
+    settings: {
+      name: string
+      settings: object
+      statusConfig: object
+      portalDesign?: { engine: string }
+    } | null
     onboarding: { complete: boolean; needsSetupWizard: boolean }
   }
 }
@@ -161,3 +182,53 @@ describe('getBootstrapData response', () => {
     expect(data.onboarding).toEqual({ complete: false, needsSetupWizard: false })
   })
 })
+
+describe('the switch preview frame', () => {
+  const switched = { engine: 'v2', attributes: {} }
+  const editor = { scope: 'dashboard', permissions: ['settings.branding'] }
+
+  beforeEach(() => {
+    hoisted.getWorkspaceSettings.mockReset()
+    hoisted.getWorkspaceSettings.mockResolvedValue(workspaceSettings(setupState()))
+    hoisted.getOptionalAuth.mockReset()
+    hoisted.switchPreviewView.mockReset()
+    hoisted.switchPreviewView.mockResolvedValue(switched)
+  })
+
+  it('draws the portal switched for someone who can edit its branding', async () => {
+    hoisted.getOptionalAuth.mockResolvedValue(editor)
+    const data = await getBootstrapData({ designPreview: 'switch' })
+    expect(data.settings?.portalDesign).toEqual(switched)
+    expect(data.settings?.settings).toEqual({})
+  })
+
+  it('draws it as it is for anyone else, or for an unknown request', async () => {
+    hoisted.getOptionalAuth.mockResolvedValue(null)
+    expect(
+      (await getBootstrapData({ designPreview: 'switch' })).settings?.portalDesign
+    ).toBeUndefined()
+    hoisted.getOptionalAuth.mockResolvedValue({ ...editor, permissions: ['posts.read'] })
+    expect(
+      (await getBootstrapData({ designPreview: 'switch' })).settings?.portalDesign
+    ).toBeUndefined()
+    hoisted.getOptionalAuth.mockResolvedValue({ ...editor, scope: 'widget' })
+    expect(
+      (await getBootstrapData({ designPreview: 'switch' })).settings?.portalDesign
+    ).toBeUndefined()
+
+    hoisted.getOptionalAuth.mockResolvedValue(editor)
+    expect(
+      (await getBootstrapData({ designPreview: 'other' })).settings?.portalDesign
+    ).toBeUndefined()
+    expect((await getBootstrapData()).settings?.portalDesign).toBeUndefined()
+    expect(hoisted.switchPreviewView).toHaveBeenCalledTimes(0)
+  })
+
+  it('draws it as it is when there is nothing to switch', async () => {
+    hoisted.getOptionalAuth.mockResolvedValue(editor)
+    hoisted.switchPreviewView.mockResolvedValue(null)
+    expect(
+      (await getBootstrapData({ designPreview: 'switch' })).settings?.portalDesign
+    ).toBeUndefined()
+  })
+})
diff --git a/apps/web/src/lib/server/functions/bootstrap.ts b/apps/web/src/lib/server/functions/bootstrap.ts
index 14d66ae612..3ade8aa2a1 100644
--- a/apps/web/src/lib/server/functions/bootstrap.ts
+++ b/apps/web/src/lib/server/functions/bootstrap.ts
@@ -183,153 +183,187 @@ function clientSafeSettings(settings: WorkspaceSettings): WorkspaceSettings {
   return { ...redacted, settings: {} as WorkspaceSettings['settings'] }
 }
 
+/**
+ * The settings with the portal drawn as it would be after switching to the
+ * design, for the preview frame Settings › Portal shows beside today's. Only
+ * for someone who can edit the portal's branding; anyone else, or a portal
+ * with nothing to switch, gets the settings unchanged.
+ */
+async function withSwitchPreview(settings: WorkspaceSettings): Promise<WorkspaceSettings> {
+  const [{ getOptionalAuth }, { PERMISSIONS }] = await Promise.all([
+    import('./auth-helpers'),
+    import('@/lib/shared/permissions'),
+  ])
+  const auth = await getOptionalAuth()
+  if (auth?.scope !== 'dashboard' || !auth.permissions.includes(PERMISSIONS.SETTINGS_BRANDING)) {
+    return settings
+  }
+  const { switchPreviewView } = await import('@/lib/server/domains/design/switch')
+  const view = await switchPreviewView()
+  return view ? { ...settings, portalDesign: view } : settings
+}
+
+/** What a page asks the bootstrap for beyond the defaults. */
+export interface BootstrapOptions {
+  /** `switch`: draw the portal as it would look switched to the design. */
+  designPreview?: 'switch'
+}
+
 let _initialized = false
 
-const getBootstrapDataInternal = createServerOnlyFn(async (): Promise<BootstrapData> => {
-  const [
-    { getWorkspaceSettings },
-    { getRegisteredAuthProviders },
-    { config },
-    { getRequestHeaders, setResponseHeader },
-    { resolveHelpCenterBaseUrl },
-  ] = await Promise.all([
-    import('@/lib/server/domains/settings/settings.service'),
-    import('@/lib/server/auth/registered-providers'),
-    import('@/lib/server/config'),
-    import('@tanstack/react-start/server'),
-    import('@/lib/server/domains/help-center/help-center-domain.service'),
-  ])
+const getBootstrapDataInternal = createServerOnlyFn(
+  async (options: BootstrapOptions = {}): Promise<BootstrapData> => {
+    const [
+      { getWorkspaceSettings },
+      { getRegisteredAuthProviders },
+      { config },
+      { getRequestHeaders, setResponseHeader },
+      { resolveHelpCenterBaseUrl },
+    ] = await Promise.all([
+      import('@/lib/server/domains/settings/settings.service'),
+      import('@/lib/server/auth/registered-providers'),
+      import('@/lib/server/config'),
+      import('@tanstack/react-start/server'),
+      import('@/lib/server/domains/help-center/help-center-domain.service'),
+    ])
 
-  // Single principal read returns both session.principalType + userRole;
-  // run in parallel with the settings fetch.
-  const [{ session, role: userRole }, settings, registeredAuthProviders] = await Promise.all([
-    getSessionAndRole(),
-    getWorkspaceSettings(),
-    getRegisteredAuthProviders(),
-  ])
+    // Single principal read returns both session.principalType + userRole;
+    // run in parallel with the settings fetch.
+    const [{ session, role: userRole }, settings, registeredAuthProviders] = await Promise.all([
+      getSessionAndRole(),
+      getWorkspaceSettings(),
+      getRegisteredAuthProviders(),
+    ])
 
-  // One-time initialization on first request.
-  //
-  // Role-gated, and the gate is not cosmetic. Telemetry is default-on and this
-  // path had none, so a `role=web` replica walked every workspace in the registry
-  // once an hour — which is precisely what SAAS-HOSTING-STACK.md §1's
-  // scale-to-zero argument says a web replica does not do ("a QUACKBACK_ROLE=web
-  // replica runs none of them"), and what Piece 2 measured. Fixing the
-  // wrong-workspace problem by making the sweep fleet-wide widened its blast
-  // radius from one workspace's database to every workspace's, including on replicas
-  // that must stay silent to let their computes suspend.
-  //
-  // `shouldRunWorkers()` is the same predicate `startup.ts` gates the sweepers
-  // behind, so telemetry now lives on the same side of the split as the rest
-  // of the background work.
-  if (!_initialized && shouldRunWorkers()) {
-    _initialized = true
+    // One-time initialization on first request.
+    //
+    // Role-gated, and the gate is not cosmetic. Telemetry is default-on and this
+    // path had none, so a `role=web` replica walked every workspace in the registry
+    // once an hour — which is precisely what SAAS-HOSTING-STACK.md §1's
+    // scale-to-zero argument says a web replica does not do ("a QUACKBACK_ROLE=web
+    // replica runs none of them"), and what Piece 2 measured. Fixing the
+    // wrong-workspace problem by making the sweep fleet-wide widened its blast
+    // radius from one workspace's database to every workspace's, including on replicas
+    // that must stay silent to let their computes suspend.
+    //
+    // `shouldRunWorkers()` is the same predicate `startup.ts` gates the sweepers
+    // behind, so telemetry now lives on the same side of the split as the rest
+    // of the background work.
+    if (!_initialized && shouldRunWorkers()) {
+      _initialized = true
 
-    // Delay telemetry to let the DB connection initialize
-    setTimeout(() => {
-      // Detached from the request that happened to arm it.
-      //
-      // AsyncLocalStorage carries the arming request's store into this timer,
-      // into `startTelemetry`, and into the hourly `setInterval` it arms — for
-      // the life of the process. Under pooled tenancy that store carries the
-      // WORKSPACE SCOPE, and `withSweepLock` fans a tick across the fleet only
-      // when no scope is active. So without this, whichever workspace rendered the
-      // pod's first page would own the fleet's telemetry forever: the hourly
-      // claim would take the lock in *its* database, no other workspace would ever
-      // be pinged, and `telemetry/instance-id.ts` would keep issuing an
-      // unlocked read-modify-write of *its* `settings.metadata` — the write
-      // SAAS-HOSTING-STACK.md §3 names as able to drop the fingerprint stamp.
-      //
-      // `_initialized` itself is fine shared: it is a once-per-process latch,
-      // and process-lifetime is exactly what it should mean. The bug was that
-      // the work it gates inherited a request's identity.
-      void runWithoutLogContext(async () => {
-        try {
-          const { startTelemetry } = await import('@/lib/server/telemetry')
-          await startTelemetry()
-        } catch {
-          // Silent failure -- telemetry must never affect the application
-        }
-      })
-    }, 10_000)
-  }
+      // Delay telemetry to let the DB connection initialize
+      setTimeout(() => {
+        // Detached from the request that happened to arm it.
+        //
+        // AsyncLocalStorage carries the arming request's store into this timer,
+        // into `startTelemetry`, and into the hourly `setInterval` it arms — for
+        // the life of the process. Under pooled tenancy that store carries the
+        // WORKSPACE SCOPE, and `withSweepLock` fans a tick across the fleet only
+        // when no scope is active. So without this, whichever workspace rendered the
+        // pod's first page would own the fleet's telemetry forever: the hourly
+        // claim would take the lock in *its* database, no other workspace would ever
+        // be pinged, and `telemetry/instance-id.ts` would keep issuing an
+        // unlocked read-modify-write of *its* `settings.metadata` — the write
+        // SAAS-HOSTING-STACK.md §3 names as able to drop the fingerprint stamp.
+        //
+        // `_initialized` itself is fine shared: it is a once-per-process latch,
+        // and process-lifetime is exactly what it should mean. The bug was that
+        // the work it gates inherited a request's identity.
+        void runWithoutLogContext(async () => {
+          try {
+            const { startTelemetry } = await import('@/lib/server/telemetry')
+            await startTelemetry()
+          } catch {
+            // Silent failure -- telemetry must never affect the application
+          }
+        })
+      }, 10_000)
+    }
 
-  const headers = getRequestHeaders()
-  const themeCookie = getThemeCookie(headers.get('cookie') ?? null)
-  const portalThemeCookie = getPortalThemeCookie(headers.get('cookie') ?? null)
-  const updateBannerDismissedVersion = getUpdateBannerDismissedVersionCookie(
-    headers.get('cookie') ?? null
-  )
-  const acceptLanguageLocale = resolveLocale(headers.get('accept-language'))
+    const headers = getRequestHeaders()
+    const themeCookie = getThemeCookie(headers.get('cookie') ?? null)
+    const portalThemeCookie = getPortalThemeCookie(headers.get('cookie') ?? null)
+    const updateBannerDismissedVersion = getUpdateBannerDismissedVersionCookie(
+      headers.get('cookie') ?? null
+    )
+    const acceptLanguageLocale = resolveLocale(headers.get('accept-language'))
 
-  // Ask for the prefers-color-scheme client hint, so Chromium sends the OS
-  // preference with later requests and a `system` theme is rendered here. A
-  // document rendered without it (a first visit, Firefox, Safari) resolves the
-  // theme in a <head> script instead (see colorSchemeHintHeaders).
-  for (const [name, value] of Object.entries(colorSchemeHintHeaders())) {
-    setResponseHeader(name, value)
-  }
-  // This document is keyed on every input we render into it: the `theme` cookie
-  // (and the session/role embedded in the dehydrated context), Accept-Language
-  // for `<html lang>`/`dir`, the color-scheme hint, and now Host (below,
-  // baseUrl switches to the help center's verified custom domain when the
-  // request arrives on it). List them all so a shared cache can never serve
-  // e.g. a dark-cookie document to a no-cookie visitor that happens to share
-  // the same hint.
-  setResponseHeader('Vary', 'Cookie, Accept-Language, Sec-CH-Prefers-Color-Scheme, Host')
-  const prefersColorScheme = parsePrefersColorScheme(headers.get('sec-ch-prefers-color-scheme'))
+    // Ask for the prefers-color-scheme client hint, so Chromium sends the OS
+    // preference with later requests and a `system` theme is rendered here. A
+    // document rendered without it (a first visit, Firefox, Safari) resolves the
+    // theme in a <head> script instead (see colorSchemeHintHeaders).
+    for (const [name, value] of Object.entries(colorSchemeHintHeaders())) {
+      setResponseHeader(name, value)
+    }
+    // This document is keyed on every input we render into it: the `theme` cookie
+    // (and the session/role embedded in the dehydrated context), Accept-Language
+    // for `<html lang>`/`dir`, the color-scheme hint, and now Host (below,
+    // baseUrl switches to the help center's verified custom domain when the
+    // request arrives on it). List them all so a shared cache can never serve
+    // e.g. a dark-cookie document to a no-cookie visitor that happens to share
+    // the same hint.
+    setResponseHeader('Vary', 'Cookie, Accept-Language, Sec-CH-Prefers-Color-Scheme, Host')
+    const prefersColorScheme = parsePrefersColorScheme(headers.get('sec-ch-prefers-color-scheme'))
 
-  // Canonical URLs switch to the help center's custom domain when the
-  // request actually arrived on it (domains/languages §1) -- everywhere else
-  // (boards, changelog, etc.) this is a no-op and baseUrl is just BASE_URL.
-  const baseUrl = resolveHelpCenterBaseUrl({
-    domainConfig: settings?.helpCenterConfig?.domain,
-    currentHost: headers.get('host'),
-    fallback: config.baseUrl,
-  })
-  const cloud = resolveCloudConfig(
-    (settings?.settings as { cloud?: StoredCloudConfig | null } | undefined)?.cloud
-  )
-  const setupState = getSetupState(settings?.settings?.setupState ?? null)
+    // Canonical URLs switch to the help center's custom domain when the
+    // request actually arrived on it (domains/languages §1) -- everywhere else
+    // (boards, changelog, etc.) this is a no-op and baseUrl is just BASE_URL.
+    const baseUrl = resolveHelpCenterBaseUrl({
+      domainConfig: settings?.helpCenterConfig?.domain,
+      currentHost: headers.get('host'),
+      fallback: config.baseUrl,
+    })
+    const cloud = resolveCloudConfig(
+      (settings?.settings as { cloud?: StoredCloudConfig | null } | undefined)?.cloud
+    )
+    const setupState = getSetupState(settings?.settings?.setupState ?? null)
 
-  return {
-    baseUrl,
-    session,
-    settings: settings ? clientSafeSettings(settings) : null,
-    onboarding: {
-      complete: isOnboardingComplete(setupState),
-      needsSetupWizard: needsCloudOnboardingWizard(setupState),
-    },
-    userRole,
-    themeCookie,
-    portalThemeCookie,
-    prefersColorScheme,
-    managedFieldPaths: settings?.managedFieldPaths ?? [],
-    registeredAuthProviders,
-    acceptLanguageLocale,
-    updateBannerDismissedVersion,
-    billingEnabled: cloud.enabled && (cloud.canUpgrade || cloud.canManageBilling),
-    cloudEnabled: cloud.enabled,
-    productAnalytics: config.productAnalytics
-      ? {
-          key: config.productAnalytics.key,
-          apiHost: config.productAnalytics.host,
-          uiHost: config.productAnalytics.uiHost,
-          sessionRecording: config.productAnalytics.sessionRecording,
-          maskText: config.productAnalytics.maskText,
-          maskInputs: config.productAnalytics.maskInputs,
-          workspaceId: await analyticsWorkspaceKey(
-            getCurrentWorkspace()?.workspaceKey,
-            typeof settings?.settings?.id === 'string' ? settings.settings.id : null
-          ),
-        }
-      : null,
+    return {
+      baseUrl,
+      session,
+      settings: settings
+        ? options.designPreview === 'switch'
+          ? await withSwitchPreview(clientSafeSettings(settings))
+          : clientSafeSettings(settings)
+        : null,
+      onboarding: {
+        complete: isOnboardingComplete(setupState),
+        needsSetupWizard: needsCloudOnboardingWizard(setupState),
+      },
+      userRole,
+      themeCookie,
+      portalThemeCookie,
+      prefersColorScheme,
+      managedFieldPaths: settings?.managedFieldPaths ?? [],
+      registeredAuthProviders,
+      acceptLanguageLocale,
+      updateBannerDismissedVersion,
+      billingEnabled: cloud.enabled && (cloud.canUpgrade || cloud.canManageBilling),
+      cloudEnabled: cloud.enabled,
+      productAnalytics: config.productAnalytics
+        ? {
+            key: config.productAnalytics.key,
+            apiHost: config.productAnalytics.host,
+            uiHost: config.productAnalytics.uiHost,
+            sessionRecording: config.productAnalytics.sessionRecording,
+            maskText: config.productAnalytics.maskText,
+            maskInputs: config.productAnalytics.maskInputs,
+            workspaceId: await analyticsWorkspaceKey(
+              getCurrentWorkspace()?.workspaceKey,
+              typeof settings?.settings?.id === 'string' ? settings.settings.id : null
+            ),
+          }
+        : null,
+    }
   }
-})
+)
 
-export const getBootstrapData = createServerFn({ method: 'GET' }).handler(
-  async (): Promise<BootstrapData> => {
+export const getBootstrapData = createServerFn({ method: 'GET' })
+  .validator((data: BootstrapOptions | undefined): BootstrapOptions =>
+    data?.designPreview === 'switch' ? { designPreview: 'switch' } : {}
+  )
+  .handler(async ({ data }): Promise<BootstrapData> => {
     log.debug('get bootstrap data')
-    return await getBootstrapDataInternal()
-  }
-)
+    return await getBootstrapDataInternal(data)
+  })
diff --git a/apps/web/src/lib/server/functions/portal-design.ts b/apps/web/src/lib/server/functions/portal-design.ts
index 56d64b5f49..1b4e1b5014 100644
--- a/apps/web/src/lib/server/functions/portal-design.ts
+++ b/apps/web/src/lib/server/functions/portal-design.ts
@@ -52,6 +52,32 @@ export const listPortalDesignVersionsFn = createServerFn({ method: 'GET' }).hand
   return listDesignVersions()
 })
 
+export const getPortalDesignSwitchFn = createServerFn({ method: 'GET' }).handler(async () => {
+  await requireAuth({ permission: PERMISSIONS.SETTINGS_BRANDING })
+  const { readDesignSwitch } = await import('@/lib/server/domains/design/switch')
+  return readDesignSwitch()
+})
+
+export const switchPortalDesignFn = createServerFn({ method: 'POST' }).handler(async () => {
+  const auth = await requireAuth({ permission: PERMISSIONS.SETTINGS_BRANDING })
+  const { designAuthor } = await import('@/lib/server/domains/design/design-author')
+  const author = await designAuthor(auth)
+  const { switchToDesign } = await import('@/lib/server/domains/design/switch')
+  const result = await switchToDesign(author)
+  if (result.ok) log.info({ revision: result.number }, 'portal switched to the design')
+  return result
+})
+
+export const switchBackPortalDesignFn = createServerFn({ method: 'POST' }).handler(async () => {
+  const auth = await requireAuth({ permission: PERMISSIONS.SETTINGS_BRANDING })
+  const { designAuthor } = await import('@/lib/server/domains/design/design-author')
+  const author = await designAuthor(auth)
+  const { switchBackFromDesign } = await import('@/lib/server/domains/design/switch')
+  const result = await switchBackFromDesign(author)
+  if (result.ok) log.info('portal switched back to the old theme')
+  return result
+})
+
 export const restorePortalDesignVersionFn = createServerFn({ method: 'POST' })
   .validator(z.object({ revisionId: typeIdSchema('portal_design_revision') }))
   .handler(async ({ data }) => {
diff --git a/apps/web/src/lib/server/policy/authz-matrix/MATRIX.md b/apps/web/src/lib/server/policy/authz-matrix/MATRIX.md
index 250c8b1dc4..1fdb42651e 100644
--- a/apps/web/src/lib/server/policy/authz-matrix/MATRIX.md
+++ b/apps/web/src/lib/server/policy/authz-matrix/MATRIX.md
@@ -101,7 +101,7 @@ Profiles: **Owner** = admin class + an admin-owned full API key (scoped keys hol
 
 ## 2. Surfaces and their enforced authorization
 
-### Server functions (`requireAuth`) — 764 surfaces
+### Server functions (`requireAuth`) — 767 surfaces
 
 | Surface | Enforces |
 | --- | --- |
@@ -537,6 +537,9 @@ Profiles: **Owner** = admin class + an admin-owned full API key (scoped keys hol
 | `lib/server/functions/portal-design.ts`::discardPortalDesignDraftFn | settings.branding |
 | `lib/server/functions/portal-design.ts`::publishPortalDesignFn | settings.branding |
 | `lib/server/functions/portal-design.ts`::listPortalDesignVersionsFn | settings.branding |
+| `lib/server/functions/portal-design.ts`::getPortalDesignSwitchFn | settings.branding |
+| `lib/server/functions/portal-design.ts`::switchPortalDesignFn | settings.branding |
+| `lib/server/functions/portal-design.ts`::switchBackPortalDesignFn | settings.branding |
 | `lib/server/functions/portal-design.ts`::restorePortalDesignVersionFn | settings.branding |
 | `lib/server/functions/portal-invites.ts`::sendPortalInviteFn | settings.manage |
 | `lib/server/functions/portal-invites.ts`::cancelPortalInviteFn | settings.manage |
@@ -1099,7 +1102,7 @@ Key scopes are enforced: an API key holds exactly its stored scopes (owner permi
 
 ## 4. Entry points without a requireAuth/key gate
 
-228 of 1114 entry points hold no `requireAuth` / `withApiKeyAuth` / `requireTeamAuth` gate.
+228 of 1117 entry points hold no `requireAuth` / `withApiKeyAuth` / `requireTeamAuth` gate.
 Each is expected to be intentionally public, a pre-auth flow, a signature-verified webhook, or a handler that delegates auth (e.g. the MCP route).
 **Adding a row here is an access-control change** — confirm the new entry point is meant to be reachable without a gate.
 
diff --git a/apps/web/src/lib/shared/design/__tests__/convert.test.ts b/apps/web/src/lib/shared/design/__tests__/convert.test.ts
index b58cfdc803..ea3bc28028 100644
--- a/apps/web/src/lib/shared/design/__tests__/convert.test.ts
+++ b/apps/web/src/lib/shared/design/__tests__/convert.test.ts
@@ -3,7 +3,12 @@ import { expandTheme } from '@/lib/shared/theme/expand'
 import { normalizeFontSans } from '@/lib/shared/theme/generator'
 import { themePresets } from '@/lib/shared/theme/presets'
 import type { ThemeConfig, ThemeVariables } from '@/lib/shared/theme/types'
-import { convertLegacyBranding, CONVERSION_DELTA_TOKENS, leadingFamily } from '../convert'
+import {
+  carriesThemeVariable,
+  convertLegacyBranding,
+  CONVERSION_DELTA_TOKENS,
+  leadingFamily,
+} from '../convert'
 import { normaliseColor } from '../color'
 import { oklchToHex } from '@/lib/shared/theme/colors'
 import { resolveDesign } from '../resolve'
@@ -176,3 +181,31 @@ describe('convertLegacyBranding', () => {
     expect(portalDesign.safeParse(doc).success).toBe(true)
   })
 })
+
+describe('carriesThemeVariable', () => {
+  it('answers as the conversion does', () => {
+    const accent = (value: string) =>
+      convertLegacyBranding({ brandingConfig: { light: { primary: value } } }).brand.light.accent
+    expect(carriesThemeVariable('primary', '#0f766e', 'light')).toBe(true)
+    expect(accent('#0f766e')).toBe('#0f766e')
+    expect(carriesThemeVariable('primary', 'var(--brand)', 'light')).toBe(false)
+    expect(accent('var(--brand)')).toBe(accent('nonsense'))
+
+    expect(carriesThemeVariable('radius', '0px', 'light')).toBe(true)
+    expect(
+      convertLegacyBranding({ brandingConfig: { light: { radius: '0px' } } }).shape.corners
+    ).toBe('sharp')
+    expect(carriesThemeVariable('radius', 'calc(1rem / 2)', 'light')).toBe(false)
+    expect(carriesThemeVariable('radius', '0px', 'dark')).toBe(false)
+
+    expect(carriesThemeVariable('fontSans', '"Fraunces", serif', 'light')).toBe(true)
+    expect(
+      convertLegacyBranding({ brandingConfig: { light: { fontSans: '"Fraunces", serif' } } }).brand
+        .fonts.body
+    ).toEqual({ kind: 'bundled', id: 'fraunces' })
+    expect(carriesThemeVariable('fontSans', '"Comic Sans MS", cursive', 'light')).toBe(false)
+    expect(carriesThemeVariable('fontSans', '"Fraunces", serif', 'dark')).toBe(false)
+
+    expect(carriesThemeVariable('ring', '#0f766e', 'light')).toBe(false)
+  })
+})
diff --git a/apps/web/src/lib/shared/design/convert.ts b/apps/web/src/lib/shared/design/convert.ts
index b49c9eb969..fb9c957c26 100644
--- a/apps/web/src/lib/shared/design/convert.ts
+++ b/apps/web/src/lib/shared/design/convert.ts
@@ -75,9 +75,11 @@ function palette(vars: ThemeVariables | undefined, base: typeof DEFAULT_LIGHT_BA
   return Object.fromEntries(Object.entries(out).filter(([, v]) => v !== undefined)) as Palette
 }
 
+const RADIUS = /^(\d+(?:\.\d+)?)(rem|px|em)?$/
+
 function corners(radius: unknown): PortalDesign['shape']['corners'] {
   if (typeof radius !== 'string') return 'rounded'
-  const match = /^(\d+(?:\.\d+)?)(rem|px|em)?$/.exec(radius.trim())
+  const match = RADIUS.exec(radius.trim())
   if (!match) return 'rounded'
   const rem = match[2] === 'px' ? Number(match[1]) / 16 : Number(match[1])
   if (rem === 0) return 'sharp'
@@ -96,11 +98,43 @@ export function leadingFamily(stack: string): string {
 }
 
 /** The bundled font a saved stack leads with; presets wrote stacks that differ after the first family. */
+function bundledFont(fontSans: string) {
+  const family = leadingFamily(normalizeFontSans(fontSans))
+  return BUNDLED_FONT_IDS.find((font) => leadingFamily(bundledFontStack(font)) === family)
+}
+
 function bodyFont(fontSans: unknown): PortalDesign['brand']['fonts']['body'] {
   if (typeof fontSans !== 'string') return { kind: 'bundled', id: 'inter' }
-  const family = leadingFamily(normalizeFontSans(fontSans))
-  const id = BUNDLED_FONT_IDS.find((font) => leadingFamily(bundledFontStack(font)) === family)
-  return { kind: 'bundled', id: id ?? 'inter' }
+  return { kind: 'bundled', id: bundledFont(fontSans) ?? 'inter' }
+}
+
+/** The theme variables the converter reads, each with the design field it becomes. */
+export const CARRIED_THEME_VARIABLES = {
+  primary: 'accent',
+  background: 'background',
+  foreground: 'text colour',
+  card: 'surface',
+  muted: 'raised surface',
+  mutedForeground: 'muted text colour',
+  border: 'border colour',
+  radius: 'corners',
+  fontSans: 'font',
+} as const satisfies Partial<Record<keyof ThemeVariables, string>>
+
+/**
+ * Whether the converter carries this value of a theme variable into a design.
+ * Corners and the font come from the light theme only.
+ */
+export function carriesThemeVariable(
+  name: keyof ThemeVariables,
+  value: string,
+  mode: 'light' | 'dark'
+): boolean {
+  if (name === 'radius' || name === 'fontSans') {
+    if (mode === 'dark') return false
+    return name === 'radius' ? RADIUS.test(value.trim()) : bundledFont(value) !== undefined
+  }
+  return name in CARRIED_THEME_VARIABLES && color(value) !== undefined
 }
 
 const DISPLAY: Record<string, PortalDesign['brand']['logo']['display']> = {
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index 84fd9f343b..e2ffcffa15 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -78,9 +78,13 @@ export function isOnboardingExempt(pathname: string): boolean {
 }
 
 // The settings arrive already redacted: getBootstrapData scrubs them on the
-// server, since its response also answers client-side navigations.
-async function loadRootContext() {
-  const { settings, ...bootstrap } = await getBootstrapData()
+// server, since its response also answers client-side navigations. The
+// switch preview frame (`?design=switch`) asks for the portal drawn as it
+// would be after switching to the design.
+async function loadRootContext(search: Record<string, unknown>) {
+  const { settings, ...bootstrap } = await getBootstrapData({
+    data: search.design === 'switch' ? { designPreview: 'switch' } : undefined,
+  })
   return { ...bootstrap, settings }
 }
 
@@ -95,7 +99,7 @@ const rootContext = createRouteContextMemo<RootContext>()
 
 export const Route = createRootRouteWithContext<RouterContext>()({
   beforeLoad: async ({ location }) => {
-    const context = await rootContext.get(loadRootContext)
+    const context = await rootContext.get(() => loadRootContext(location.search))
     const { session, userRole, onboarding } = context
 
     if (!isOnboardingExempt(location.pathname)) {
diff --git a/apps/web/src/routes/_portal.tsx b/apps/web/src/routes/_portal.tsx
index 623101bbef..a8eeb56743 100644
--- a/apps/web/src/routes/_portal.tsx
+++ b/apps/web/src/routes/_portal.tsx
@@ -69,6 +69,7 @@ export const Route = createFileRoute('/_portal')({
     error?: string
     theme?: 'light' | 'dark'
     preview?: boolean
+    design?: 'switch'
   } => ({
     auth:
       search.auth === 'signin' || search.auth === 'signup' ? (search.auth as string) : undefined,
@@ -79,9 +80,12 @@ export const Route = createFileRoute('/_portal')({
     // postMessage draft bridge. Both retained across in-app navigation below.
     theme: search.theme === 'light' || search.theme === 'dark' ? search.theme : undefined,
     preview: search.preview === true || search.preview === 1 || search.preview === '1' || undefined,
+    // The switch preview: the portal drawn as it would be on the design
+    // (see __root.tsx), kept as the frame navigates.
+    design: search.design === 'switch' ? 'switch' : undefined,
   }),
   search: {
-    middlewares: [retainSearchParams(['theme', 'preview'])],
+    middlewares: [retainSearchParams(['theme', 'preview', 'design'])],
   },
   loaderDeps: ({ search }) => ({
     auth: search.auth,
diff --git a/apps/web/src/routes/admin/settings.portal.tsx b/apps/web/src/routes/admin/settings.portal.tsx
index d85a13fb35..fa198e821f 100644
--- a/apps/web/src/routes/admin/settings.portal.tsx
+++ b/apps/web/src/routes/admin/settings.portal.tsx
@@ -63,9 +63,14 @@ import type {
 } from '@/lib/shared/types/settings'
 import type { TiptapContent } from '@/lib/shared/db-types'
 import { readBatch } from '@/lib/client/queries/read-batch'
-import { useSessionContext, useWorkspaceSettings } from '@/lib/client/hooks/use-root-context'
+import {
+  useFeatureFlag,
+  useSessionContext,
+  useWorkspaceSettings,
+} from '@/lib/client/hooks/use-root-context'
 import { adminPageHead } from '@/lib/client/admin-head'
 import { AppearanceView } from '@/components/admin/settings/appearance/appearance-view'
+import { DesignSwitchCard } from '@/components/admin/settings/appearance/design-switch-card'
 
 export const Route = createFileRoute('/admin/settings/portal')({
   head: adminPageHead('Portal settings'),
@@ -83,8 +88,9 @@ export const Route = createFileRoute('/admin/settings/portal')({
       ensure(settingsQueries.customCss()),
       ensure(settingsQueries.portalConfig()),
       ensureBillingCatalogue(context.queryClient, context.billingEnabled),
-      // A workspace on the design engine opens on Appearance. Loaded here,
-      // not imported above: a loader's imports ship in the entry chunk.
+      // A workspace on the design engine opens on Appearance; one still on
+      // the old theme with the engine on may be offered the switch. Loaded
+      // here, not imported above: a loader's imports ship in the entry chunk.
       context.settings?.portalDesign?.engine === 'v2'
         ? import('@/lib/client/queries/portal-design').then(({ portalDesignQueries }) =>
             Promise.all([
@@ -92,7 +98,11 @@ export const Route = createFileRoute('/admin/settings/portal')({
               ensure(portalDesignQueries.aiStatus()),
             ])
           )
-        : undefined,
+        : context.settings?.featureFlags?.portalDesignV2
+          ? import('@/lib/client/queries/portal-design').then(({ portalDesignQueries }) =>
+              ensure(portalDesignQueries.switch())
+            )
+          : undefined,
     ])
   },
   component: PortalSettingsPage,
@@ -138,6 +148,7 @@ function PortalPage() {
   const [, startTransition] = useTransition()
   // Display-only: the name is edited on Workspace > General.
   const workspaceName = settings?.name || ''
+  const designEngineOn = useFeatureFlag('portalDesignV2')
 
   const { data: brandingConfig = {} } = useSuspenseQuery(settingsQueries.branding())
   const { data: logoData } = useSuspenseQuery(settingsQueries.logo())
@@ -285,6 +296,14 @@ function PortalPage() {
 
   return (
     <SettingsPage page="/admin/settings/portal" width="wide">
+      {designEngineOn && (
+        <div className="mb-6">
+          <DesignSwitchCard
+            workspaceName={workspaceName}
+            faviconUrl={settings?.faviconData?.url ?? logoData?.url ?? null}
+          />
+        </div>
+      )}
       {/* Controls left, live portal preview right (sticky). */}
       <div className="grid grid-cols-1 xl:grid-cols-[minmax(360px,440px)_minmax(0,1fr)] gap-6 items-start">
         <div className="space-y-4 min-w-0">

From 0571517f4658da59305799a1354a8233bea2d427 Mon Sep 17 00:00:00 2001
From: James Morton <james.morton@quackback.io>
Date: Sat, 31 Oct 2026 07:00:56 +0000
Subject: [PATCH 2/2] test(design): type the switch card's seeded state

---
 .../admin/settings/appearance/__tests__/design-switch.test.tsx | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/components/admin/settings/appearance/__tests__/design-switch.test.tsx b/apps/web/src/components/admin/settings/appearance/__tests__/design-switch.test.tsx
index 112613a4fa..a592c28bae 100644
--- a/apps/web/src/components/admin/settings/appearance/__tests__/design-switch.test.tsx
+++ b/apps/web/src/components/admin/settings/appearance/__tests__/design-switch.test.tsx
@@ -9,6 +9,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
 import type { ReactNode } from 'react'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import type { DesignSwitch } from '@/lib/server/domains/design/switch'
 
 const server = vi.hoisted(() => ({
   invalidations: 0,
@@ -53,7 +54,7 @@ const REPORT = {
   carried: [{ message: '--primary on :root becomes the accent.' }],
 }
 
-function withClient(ui: ReactNode, state: unknown) {
+function withClient(ui: ReactNode, state: DesignSwitch) {
   const client = new QueryClient({ defaultOptions: { queries: { staleTime: Infinity } } })
   client.setQueryData(portalDesignQueries.switch().queryKey, state)
   client.setQueryData(portalDesignQueries.versions().queryKey, [])