feat: add Liquid Glass interface style with settings selector

Adds a second theme style emulating modern macOS liquid glass,
orthogonal to the existing system/light/dark color-scheme toggle:

- ThemeProvider gains themeStyle (classic|glass), persisted to
  localStorage and synced across tabs via data-theme-style on <html>
- Glass CSS: palette-derived ambient backdrop, translucent blurred
  panels with specular rims, rounder radii, plus @supports and
  prefers-reduced-transparency fallbacks
- Settings page gains an Appearance section with a Classic vault /
  Liquid glass selector
- Phoenix app shell bootstraps data-theme-style before hydration to
  avoid a style flash

Closes TASK-31.

Author: cfbender

.backlog/tasks/task-31 - Add-Liquid-Glass-theme-style-with-settings-selector.md

@@ -0,0 +1,48 @@
+---
+id: TASK-31
+title: Add Liquid Glass theme style with settings selector
+status: Done
+assignee:
+  - '@cfbender'
+created_date: '2026-08-04 15:53'
+updated_date: '2026-08-04 16:04'
+labels: []
+dependencies: []
+ordinal: 46000
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Add a second visual theme that emulates modern macOS Liquid Glass (translucent, blurred, highly rounded surfaces over an ambient backdrop). Users pick between the existing Classic look and Liquid Glass via a selector on the Settings page. The style is orthogonal to the existing System/Light/Dark color-scheme toggle so glass works in both light and dark.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Settings page has an Appearance section with a selector offering Classic and Liquid Glass
+- [x] #2 Selecting Liquid Glass applies translucent blurred surfaces, rounder radii, and an ambient backdrop across the app shell, cards, dialogs, dropdowns, and form controls
+- [x] #3 Choice persists across reloads and tabs and composes with the existing system/light/dark theme toggle
+- [x] #4 Reduced-transparency/motion preferences and browsers without backdrop-filter still get readable UI
+- [x] #5 Typecheck and react tests pass
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Extend ThemeProvider (assets/react/src/lib/theme.tsx) with an orthogonal themeStyle dimension: classic | glass, persisted to localStorage key manavault:theme-style, applied as data-theme-style on <html>, synced across tabs like theme.
+2. Add glass CSS in assets/css/app.css scoped to html[data-theme-style=glass]: rounder daisyUI radius tokens, ambient fixed multi-hue backdrop derived from theme tokens, translucent blurred surfaces (backdrop-filter blur+saturate) for header, cards, dropdown/menu, modal boxes, inputs/selects/buttons, with inset highlight rims; fallbacks via @supports and prefers-reduced-transparency.
+3. Add AppearanceSection to Settings (assets/react/src/pages/settings/) using PageSection + card pattern with two selectable style options (Classic, Liquid Glass) wired to useTheme().
+4. Verify: aube typecheck/tests, visual check in browser in light+dark.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Theme style is orthogonal to light/dark: data-theme-style on <html>, localStorage key manavault:theme-style (absent = classic), bootstrapped pre-React in app_controller.ex to avoid style flash and synced across tabs via storage events. Glass CSS targets .card/.dropdown-content/Radix dialog panels/inputs plus app-shell header; card tiles do not use .card so grid perf is unaffected; fullscreen-printing-dialog keeps its bespoke background. Verified via headless Chrome CDP screenshots: classic light unchanged, glass light+dark on /settings and /decks, prefers-reduced-transparency emulation renders opaque panels.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added a Liquid Glass interface style: ThemeProvider gained themeStyle (classic|glass) persisted and tab-synced; app.css defines glass tokens, palette-derived ambient backdrop, and translucent blurred panels with rounder radii plus @supports and prefers-reduced-transparency fallbacks; Settings gained an Appearance section with Classic/Liquid Glass selector; Phoenix shell bootstraps data-theme-style before hydration. Verified with typecheck, lint, react tests (15 passed), mix compile --warnings-as-errors, and headless-Chrome screenshots in light/dark/reduced-transparency.
+<!-- SECTION:FINAL_SUMMARY:END -->

assets/css/app.css

@@ -105,6 +105,106 @@
   --set-symbol-common-color: #000;
 }
 
+/* Liquid Glass theme style (macOS-inspired). Orthogonal to light/dark: it only
+   changes how surfaces render, not the color palette. Applied via
+   data-theme-style="glass" on <html>; "classic" leaves everything untouched. */
+html[data-theme-style="glass"] {
+  --radius-selector: 2rem;
+  --radius-field: 1rem;
+  --radius-box: 1.5rem;
+  --border: 1px;
+  --glass-blur: 20px;
+  --glass-surface: color-mix(in oklch, var(--color-base-100) 58%, transparent);
+  --glass-surface-raised: color-mix(in oklch, var(--color-base-200) 52%, transparent);
+  --glass-field: color-mix(in oklch, var(--color-base-100) 52%, transparent);
+  --glass-border: color-mix(in oklch, var(--color-base-content) 16%, transparent);
+  --glass-rim: color-mix(in oklch, white 45%, transparent);
+  --glass-shadow: 0 12px 32px -12px rgb(0 0 0 / 0.22), 0 1px 2px rgb(0 0 0 / 0.06);
+}
+
+html[data-theme-style="glass"][data-theme="dark"] {
+  --glass-surface: color-mix(in oklch, var(--color-base-200) 55%, transparent);
+  --glass-surface-raised: color-mix(in oklch, var(--color-base-300) 48%, transparent);
+  --glass-field: color-mix(in oklch, var(--color-base-200) 50%, transparent);
+  --glass-border: color-mix(in oklch, white 12%, transparent);
+  --glass-rim: color-mix(in oklch, white 14%, transparent);
+  --glass-shadow: 0 16px 40px -12px rgb(0 0 0 / 0.55), 0 1px 2px rgb(0 0 0 / 0.35);
+}
+
+/* Ambient backdrop the glass refracts: soft claret/brass/grove pools derived
+   from the active palette, fixed to the viewport like a desktop wallpaper. */
+html[data-theme-style="glass"] body {
+  background-color: var(--color-base-100);
+  background-image:
+    radial-gradient(
+      56rem 38rem at 14% -6%,
+      color-mix(in oklch, var(--color-primary), var(--color-base-100) 72%),
+      transparent 62%
+    ),
+    radial-gradient(
+      48rem 34rem at 104% 16%,
+      color-mix(in oklch, var(--color-accent), var(--color-base-100) 74%),
+      transparent 64%
+    ),
+    radial-gradient(
+      50rem 42rem at 28% 112%,
+      color-mix(in oklch, var(--color-secondary), var(--color-base-100) 76%),
+      transparent 62%
+    );
+  background-attachment: fixed;
+}
+
+html[data-theme-style="glass"] .app-shell-root {
+  background-color: transparent;
+}
+
+html[data-theme-style="glass"] :is(.card, .dropdown-content),
+html[data-theme-style="glass"] section[role="dialog"]:not(.fullscreen-printing-dialog) {
+  background-color: var(--glass-surface);
+  border-color: var(--glass-border);
+  -webkit-backdrop-filter: blur(var(--glass-blur)) saturate(160%);
+  backdrop-filter: blur(var(--glass-blur)) saturate(160%);
+  box-shadow:
+    inset 0 1px 0 0 var(--glass-rim),
+    var(--glass-shadow);
+}
+
+html[data-theme-style="glass"] .app-shell-header:not(.bg-transparent) {
+  background-color: color-mix(in oklch, var(--color-base-100) 50%, transparent);
+  border-bottom: 1px solid var(--glass-border);
+  -webkit-backdrop-filter: blur(24px) saturate(170%);
+  backdrop-filter: blur(24px) saturate(170%);
+}
+
+html[data-theme-style="glass"] :is(.input, .select, .textarea) {
+  background-color: var(--glass-field);
+  border-color: var(--glass-border);
+  box-shadow: inset 0 1px 0 0 color-mix(in oklch, white 18%, transparent);
+}
+
+html[data-theme-style="glass"] :is(.btn-outline, .btn-ghost):hover {
+  background-color: var(--glass-surface-raised);
+}
+
+/* Keep surfaces readable when translucency is unwanted or unsupported. */
+@supports not ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+  html[data-theme-style="glass"] :is(.card, .dropdown-content, .input, .select, .textarea),
+  html[data-theme-style="glass"] section[role="dialog"]:not(.fullscreen-printing-dialog),
+  html[data-theme-style="glass"] .app-shell-header:not(.bg-transparent) {
+    background-color: color-mix(in oklch, var(--color-base-100) 94%, transparent);
+  }
+}
+
+@media (prefers-reduced-transparency: reduce) {
+  html[data-theme-style="glass"] :is(.card, .dropdown-content, .input, .select, .textarea),
+  html[data-theme-style="glass"] section[role="dialog"]:not(.fullscreen-printing-dialog),
+  html[data-theme-style="glass"] .app-shell-header:not(.bg-transparent) {
+    background-color: var(--color-base-100);
+    -webkit-backdrop-filter: none;
+    backdrop-filter: none;
+  }
+}
+
 .fullscreen-printing-dialog {
   --card-modal-bg: color-mix(in oklch, var(--color-primary), var(--color-base-100) 88%);
   --card-modal-fg: color-mix(in oklch, var(--color-primary), black 50%);

assets/react/src/components/app-shell.tsx

@@ -116,7 +116,7 @@ export function AppShell() {
 
   return (
     <PageTitleProvider>
-      <div className="min-h-screen bg-base-100 text-base-content">
+      <div className="app-shell-root min-h-screen bg-base-100 text-base-content">
         <header
           className={cn(
             "app-shell-header sticky top-0 z-30",

assets/react/src/lib/theme.tsx

@@ -1,9 +1,16 @@
 import { createContext, type ReactNode, useContext, useEffect, useMemo, useState } from "react"
 
 type Theme = "system" | "light" | "dark"
+export type ThemeStyle = "classic" | "glass"
 
-const ThemeContext = createContext<{ theme: Theme; setTheme: (theme: Theme) => void } | null>(null)
+const ThemeContext = createContext<{
+  theme: Theme
+  setTheme: (theme: Theme) => void
+  themeStyle: ThemeStyle
+  setThemeStyle: (style: ThemeStyle) => void
+} | null>(null)
 const storageKey = "manavault:theme"
+const styleStorageKey = "manavault:theme-style"
 
 function systemTheme() {
   return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"
@@ -17,6 +24,14 @@ function storedTheme() {
   }
 }
 
+function storedThemeStyle(): ThemeStyle {
+  try {
+    return localStorage.getItem(styleStorageKey) === "glass" ? "glass" : "classic"
+  } catch {
+    return "classic"
+  }
+}
+
 function persistTheme(theme: Theme) {
   try {
     if (theme === "system") {
@@ -29,6 +44,18 @@ function persistTheme(theme: Theme) {
   }
 }
 
+function persistThemeStyle(style: ThemeStyle) {
+  try {
+    if (style === "classic") {
+      localStorage.removeItem(styleStorageKey)
+    } else {
+      localStorage.setItem(styleStorageKey, style)
+    }
+  } catch {
+    // Storage can be unavailable or full. The DOM style still applies for this page load.
+  }
+}
+
 function applyTheme(theme: Theme) {
   const resolved = theme === "system" ? systemTheme() : theme
   document.documentElement.setAttribute("data-theme", resolved)
@@ -37,20 +64,34 @@ function applyTheme(theme: Theme) {
   persistTheme(theme)
 }
 
+function applyThemeStyle(style: ThemeStyle) {
+  document.documentElement.setAttribute("data-theme-style", style)
+
+  persistThemeStyle(style)
+}
+
 export function ThemeProvider({ children }: { children: ReactNode }) {
   const [theme, setTheme] = useState<Theme>(storedTheme)
+  const [themeStyle, setThemeStyle] = useState<ThemeStyle>(storedThemeStyle)
 
   useEffect(() => {
     applyTheme(theme)
   }, [theme])
 
+  useEffect(() => {
+    applyThemeStyle(themeStyle)
+  }, [themeStyle])
+
   useEffect(() => {
     const media = window.matchMedia("(prefers-color-scheme: dark)")
     const handleSystemChange = () => {
       if (storedTheme() === "system") applyTheme("system")
     }
     const handleStorage = (event: StorageEvent) => {
       if (event.key === storageKey) setTheme((event.newValue as Theme | null) || "system")
+      if (event.key === styleStorageKey) {
+        setThemeStyle(event.newValue === "glass" ? "glass" : "classic")
+      }
     }
 
     media.addEventListener("change", handleSystemChange)
@@ -62,7 +103,7 @@ export function ThemeProvider({ children }: { children: ReactNode }) {
     }
   }, [])
 
-  const value = useMemo(() => ({ theme, setTheme }), [theme])
+  const value = useMemo(() => ({ theme, setTheme, themeStyle, setThemeStyle }), [theme, themeStyle])
 
   return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
 }

assets/react/src/pages/settings/appearance-section.tsx

@@ -0,0 +1,81 @@
+import { Check, Droplets, Vault } from "lucide-react"
+import { PageSection } from "../../components/app-shell"
+import { useTheme, type ThemeStyle } from "../../lib/theme"
+import { cn } from "../../lib/utils"
+
+const styleOptions: {
+  value: ThemeStyle
+  label: string
+  description: string
+  icon: typeof Vault
+}[] = [
+  {
+    value: "classic",
+    label: "Classic vault",
+    description: "Solid, tactile surfaces with crisp borders and compact corners.",
+    icon: Vault,
+  },
+  {
+    value: "glass",
+    label: "Liquid glass",
+    description:
+      "Translucent, blurred panels over an ambient backdrop, in the spirit of modern macOS.",
+    icon: Droplets,
+  },
+]
+
+export function AppearanceSection() {
+  const { themeStyle, setThemeStyle } = useTheme()
+
+  return (
+    <PageSection title="Appearance" count="Interface style">
+      <div className="card border border-base-300 bg-base-100 shadow-sm">
+        <div className="card-body gap-4 p-6">
+          <div>
+            <h2 className="text-2xl font-black tracking-normal">Interface style</h2>
+            <p className="mt-1 text-sm text-base-content/60">
+              Choose how surfaces render. Light and dark modes stay on the toggle in the navigation
+              and apply to both styles.
+            </p>
+          </div>
+          <div className="grid gap-3 sm:grid-cols-2">
+            {styleOptions.map((option) => {
+              const selected = themeStyle === option.value
+
+              return (
+                <button
+                  key={option.value}
+                  type="button"
+                  aria-pressed={selected}
+                  onClick={() => setThemeStyle(option.value)}
+                  className={cn(
+                    "flex items-start gap-3 rounded-box border p-4 text-left transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/35",
+                    selected
+                      ? "border-primary/50 bg-primary/10"
+                      : "border-base-300 bg-base-200/40 hover:border-primary/40",
+                  )}
+                >
+                  <option.icon
+                    className={cn(
+                      "mt-0.5 h-5 w-5 shrink-0",
+                      selected ? "text-primary" : "text-base-content/70",
+                    )}
+                  />
+                  <span className="min-w-0">
+                    <span className="flex items-center gap-2 font-bold">
+                      {option.label}
+                      {selected ? <Check className="h-4 w-4 text-primary" /> : null}
+                    </span>
+                    <span className="mt-1 block text-sm text-base-content/60">
+                      {option.description}
+                    </span>
+                  </span>
+                </button>
+              )
+            })}
+          </div>
+        </div>
+      </div>
+    </PageSection>
+  )
+}

assets/react/src/pages/settings/page.tsx

@@ -7,6 +7,7 @@ import { pluralize, present } from "../../lib/utils"
 import { AutoSortSummaryDialog } from "../collection/auto-sort-summary-dialog"
 import { AutoSortCollectionDocument } from "../collection/documents"
 import type { AutoSortCollectionResult } from "../collection/types"
+import { AppearanceSection } from "./appearance-section"
 import { BackupSettingsForm } from "./backup-settings-form"
 import { CollectionAutoSortSection } from "./collection-auto-sort-section"
 import { DefaultDeckTagsSection } from "./default-deck-tags-section"
@@ -305,7 +306,7 @@ export function SettingsPage() {
       <PageHeader
         eyebrow="Settings"
         title="Settings"
-        description="Manage the mobile shell, collection auto-sort rules, cloud backups, manual restores, and Scryfall catalog maintenance."
+        description="Manage appearance, the mobile shell, collection auto-sort rules, cloud backups, manual restores, and Scryfall catalog maintenance."
       />
 
       {settingsQuery.error ? <Alert tone="error">{errorMessage(settingsQuery.error)}</Alert> : null}
@@ -319,6 +320,8 @@ export function SettingsPage() {
       {error ? <Alert tone="error">{error}</Alert> : null}
       {message ? <Alert tone="success">{message}</Alert> : null}
 
+      <AppearanceSection />
+
       {nativeShell ? <NativeAppSection {...nativeSectionProps} /> : null}
 
       <BackupSettingsForm

lib/manavault_web/controllers/app_controller.ex

@@ -181,7 +181,27 @@ defmodule ManavaultWeb.AppController do
             if (!document.documentElement.hasAttribute("data-theme")) {
               setTheme(storedTheme());
             }
-            window.addEventListener("storage", (e) => e.key === storageKey && setTheme(e.newValue || "system"));
+
+            const styleStorageKey = "manavault:theme-style";
+
+            const storedThemeStyle = () => {
+              try {
+                return localStorage.getItem(styleStorageKey) === "glass" ? "glass" : "classic";
+              } catch {
+                return "classic";
+              }
+            };
+
+            const setThemeStyle = (style) => {
+              document.documentElement.setAttribute("data-theme-style", style === "glass" ? "glass" : "classic");
+            };
+            if (!document.documentElement.hasAttribute("data-theme-style")) {
+              setThemeStyle(storedThemeStyle());
+            }
+            window.addEventListener("storage", (e) => {
+              if (e.key === storageKey) setTheme(e.newValue || "system");
+              if (e.key === styleStorageKey) setThemeStyle(e.newValue);
+            });
 
             matchMedia("(prefers-color-scheme: dark)").addEventListener("change", () => {
               if (document.documentElement.getAttribute("data-theme-source") === "system") {