UI: liquid-glass translucency on the main window

vdavid · vdavid · commit 76be4f8aa52b · 2026-05-21T00:03:06.000+02:00
- Enable `tauri/macos-private-api` + window `transparent: true` so the WKWebView's `drawsBackground` can be turned off and the macOS `NSVisualEffectView` (Sidebar material) renders behind it. `tauri.conf.json` declares the `windowEffects` and `backgroundColor: [0,0,0,0]`
- Three new translucent bg tokens (light + dark): `--color-bg-primary` (0.85 light / 0.93 dark), `--color-bg-secondary` (0.5 light / 0.7 dark), `--color-bg-info-bar` (0.5 / 0.7). Light-mode `--color-selection-fg-cursor` darkened from `#b80808` to `#a30000` so the brown-tint + cursor-active + purple-accent corner of `row_state_matrix.go` stays at WCAG AA when `bg-primary` drops to 0.85
- `app.html` and `app.css` no longer paint an opaque `--bg` on `html` / `body` / `#loading-screen` — those were covering the visual-effect view on every paint
- One single pane base layer painted on `.file-pane &gt; .content`. Removed the per-row `bg-primary`, the `row-filler` / `column-filler` / horizontal-filler structural attempts in `FullList` / `BriefList`, and the `min-height` calc on `.listbox-region` — `.content` is the only ancestor mounted continuously across every dynamic state (loading, error, MTP, file list, etc.), so it's guaranteed exactly one base layer on every pane pixel, never zero (no transition flicker), never two (no double-paint)
- `--color-bg-stripe` switched to an opaque `#ffffff` / `#1e1e1e` base so striped rows replace the pane bg as a single opaque layer instead of stacking a second translucent layer
- Dev-mode / E2E-mode title-bar tint alpha dropped from 60% to 25% so the title bar reads as glass like the rest of the chrome while the hue still signals DEV / E2E
- New `appearance.translucency` setting (Settings &gt; Appearance &gt; Colors and formats, on by default, label "Translucency", desc "Liquid glass-y look if also enabled in your System Settings"). Wired through `settings-applier.ts` to a `data-translucency` attribute on `&lt;html&gt;`; `:root[data-translucency='off']` flips the three bg tokens back to fully opaque so the webview covers the visual-effect view
diff --git a/apps/desktop/src-tauri/Cargo.toml b/apps/desktop/src-tauri/Cargo.toml
@@ -33,7 +33,7 @@ crate-type = ["staticlib", "cdylib", "rlib"]
 tauri-build = { version = "2", features = [] }
 
 [dependencies]
-tauri = { version = "2", features = [] }
+tauri = { version = "2", features = ["macos-private-api"] }
 tauri-plugin-opener = "2"
 tauri-plugin-mcp-bridge = "0.11"
 tauri-plugin-store = "2"
diff --git a/apps/desktop/src-tauri/tauri.conf.json b/apps/desktop/src-tauri/tauri.conf.json
@@ -11,6 +11,7 @@
   },
   "app": {
     "withGlobalTauri": false,
+    "macOSPrivateApi": true,
     "windows": [
       {
         "title": "Cmdr",
@@ -25,7 +26,13 @@
           "y": 17
         },
         "hiddenTitle": true,
-        "acceptFirstMouse": true
+        "acceptFirstMouse": true,
+        "windowEffects": {
+          "effects": ["sidebar"],
+          "state": "followsWindowActiveState"
+        },
+        "backgroundColor": [0, 0, 0, 0],
+        "transparent": true
       }
     ],
     "security": {
diff --git a/apps/desktop/src/app.css b/apps/desktop/src/app.css
@@ -12,14 +12,20 @@
   color-scheme: light dark;
 
   /* === Backgrounds === */
-  --color-bg-primary: #ffffff;
-  --color-bg-secondary: #f5f5f5;
+  /* Background tokens are intentionally semi-transparent so the macOS
+     `NSVisualEffectView` (Sidebar material, applied via
+     `tauri.conf.json` › `windowEffects`) shows through with a subtle
+     wallpaper-blur — Finder-style "liquid glass". Tuned at ~88% so text
+     contrast against the underlying material still clears WCAG AA in both
+     light and dark wallpapers; verified by `a11y-contrast`. */
+  --color-bg-primary: rgba(255, 255, 255, 0.85);
+  --color-bg-secondary: rgba(245, 245, 245, 0.5);
   --color-bg-tertiary: #e8e8e8;
   /* Status-bar surface that contrasts gently with `--color-bg-secondary`.
      Light: a touch darker than secondary. Dark: a touch lighter. Used by
      `SelectionInfo` so the status band reads as distinct from the
      function-key bar below (which keeps `--color-bg-secondary`). */
-  --color-bg-info-bar: #ececec;
+  --color-bg-info-bar: rgba(236, 236, 236, 0.5);
 
   /* === Borders === */
   --color-border-strong: #bbb;
@@ -111,8 +117,14 @@
   --color-toast-success-stripe: #16a34a;
   --color-toast-success-bg: #f0fdf4;
 
-  /* === Striped rows (zebra striping for file lists) === */
-  --color-bg-stripe: color-mix(in oklch, var(--color-bg-primary), var(--color-text-primary) 4%);
+  /* === Striped rows (zebra striping for file lists) ===
+     Uses an OPAQUE `#ffffff` base (not `var(--color-bg-primary)`, which is
+     now translucent for the macOS vibrancy backdrop). Striped rows are a
+     visual replacement of the base pane bg, so they should be a single
+     opaque layer rather than a second translucent layer stacked on top of
+     `.content`'s `bg-primary` — that would double the alpha (~99.5%) and
+     produce a visible darker stripe vs non-stripe rows. */
+  --color-bg-stripe: color-mix(in oklch, #ffffff, var(--color-text-primary) 4%);
 
   /* === Volume tint palette (12 hues + none) ===
      The 100% saturated swatches shown in the Settings color picker for
@@ -154,7 +166,7 @@
    * them lives further down (search for "selection-fg fallback"). The
    * contrast checker's `row_state_matrix.go` synthesizer mirrors it. */
   --color-selection-fg-primary: #cc0000;
-  --color-selection-fg-cursor: #b80808;
+  --color-selection-fg-cursor: #a30000;
   --color-selection-fg-fallback: var(--color-text-primary);
   --color-selection-fg: var(--color-selection-fg-primary);
   /* Selection background and hairline border applied to selected rows in
@@ -358,6 +370,19 @@
   --color-age-old: var(--color-text-secondary);
 }
 
+/* === Translucency: Off ===
+   When the user disables `appearance.translucency` (Settings > Appearance >
+   Colors and formats), the three translucent bg tokens snap to fully opaque
+   values so the webview covers the macOS `NSVisualEffectView` Sidebar
+   material that sits behind it. The visual-effect view itself is set up
+   statically in `tauri.conf.json` and stays alive — disabling it at runtime
+   would need a Tauri command — but the opaque webview hides it. */
+:root[data-translucency='off'] {
+  --color-bg-primary: #ffffff;
+  --color-bg-secondary: #f5f5f5;
+  --color-bg-info-bar: #ececec;
+}
+
 /* selection-fg fallback: dark mode + pane tint + focused cursor on a selected
    row. In this state the row bg becomes the translucent yellow accent
    composited over a tinted dark surface — Y around 0.09. Even the brightest
@@ -459,12 +484,15 @@
 @media (prefers-color-scheme: dark) {
   :root {
     /* === Backgrounds === */
-    --color-bg-primary: #1e1e1e;
-    --color-bg-secondary: #2a2a2a;
+    /* Semi-transparent for the same Sidebar-material reason as light mode.
+       Slightly heavier alpha than light mode because dark backgrounds need
+       more body to keep text contrast against bright wallpapers. */
+    --color-bg-primary: rgba(30, 30, 30, 0.93);
+    --color-bg-secondary: rgba(42, 42, 42, 0.7);
     --color-bg-tertiary: #333333;
     /* Dark mode: lighter than secondary (opposite of light mode) so the
        status band lifts away from the function-key bar below. */
-    --color-bg-info-bar: #323232;
+    --color-bg-info-bar: rgba(50, 50, 50, 0.7);
 
     /* === Borders === */
     --color-border-strong: #555555;
@@ -547,6 +575,12 @@
     --color-git-portal-text: #80deea;
     --color-git-portal-subtle: color-mix(in oklch, var(--color-git-portal), transparent 85%);
 
+    /* === Striped rows (dark) ===
+       Same logic as light mode: opaque base so striped rows are a single
+       layer that replaces the pane's translucent backdrop, not a second
+       translucent layer that doubles its alpha. */
+    --color-bg-stripe: color-mix(in oklch, #1e1e1e, var(--color-text-primary) 4%);
+
     /* === Search Highlight === */
     --color-highlight: rgba(255, 213, 100, 0.9);
     --color-highlight-active: rgba(255, 150, 100, 0.9);
@@ -583,6 +617,15 @@
     --color-age-old: #d49858;
   }
 
+  /* === Translucency: Off (dark) ===
+     Same logic as light mode (see the light-mode block for the full
+     rationale): opaque values so the webview covers the visual-effect view. */
+  :root[data-translucency='off'] {
+    --color-bg-primary: #1e1e1e;
+    --color-bg-secondary: #2a2a2a;
+    --color-bg-info-bar: #323232;
+  }
+
   /* Old-WebKit fallback (dark mode). See the light-mode counterpart above for
      the full rationale. The rainbow size palette is the most visible case: it
      reaches *all* file lists once the user is in dark mode, so leaving it
@@ -912,7 +955,12 @@ body {
   width: 100%;
   height: 100%;
   overflow: hidden;
-  background-color: var(--color-bg-primary);
+  /* `html` must stay transparent so the macOS `NSVisualEffectView`
+     (Sidebar material, set in `tauri.conf.json`) shows through. The
+     opaque `--bg` in `app.html`'s inline critical CSS was the original
+     blocker; this rule is the belt-and-braces override in case the
+     inline style ever drifts. */
+  background-color: transparent;
   color: var(--color-text-primary);
   /* Disable text selection globally */
   user-select: none;
@@ -921,6 +969,14 @@ body {
   cursor: default;
 }
 
+/* `body` is intentionally transparent so the chrome bars (`.tab-bar`,
+   `.title-bar`, `.header`, `.selection-info`, etc., each painted with
+   `--color-bg-secondary` / `--color-bg-info-bar`) are the only layer between
+   the user and the `NSVisualEffectView` (Sidebar material, set in
+   `tauri.conf.json`). Without this, body's `--color-bg-primary` would paint
+   underneath every bar, compounding alpha (1 − (1 − α_body) × (1 − α_bar))
+   and pushing the chrome to ~99 % opaque. File rows have no bg of their own
+   either, so the file list area shows pure vibrancy. */
 body {
   display: flex;
   flex-direction: column;
diff --git a/apps/desktop/src/app.html b/apps/desktop/src/app.html
@@ -28,13 +28,19 @@
         }
       }
 
+      /* Background is intentionally NOT set here. The window uses an
+         `NSVisualEffectView` (Sidebar material, configured via
+         `tauri.conf.json` › `windowEffects` + `transparent: true`); the
+         WKWebView is transparent (`drawsBackground: NO`), so any opaque
+         color painted on `html` / `body` / `#loading-screen` would cover the
+         vibrancy and break the liquid-glass effect. `app.css` paints the
+         translucent `--color-bg-primary` on `body` once it loads. */
       html,
       body {
         margin: 0;
         padding: 0;
         width: 100%;
         height: 100%;
-        background-color: var(--bg);
         color: var(--text);
         font-family: -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
       }
@@ -47,7 +53,6 @@
         align-items: center;
         justify-content: center;
         z-index: 9999;
-        background-color: var(--bg);
       }
 
       .app-loader {
diff --git a/apps/desktop/src/lib/file-explorer/pane/FilePane.svelte b/apps/desktop/src/lib/file-explorer/pane/FilePane.svelte
@@ -2624,6 +2624,16 @@
         flex-direction: column;
         /* Anchor for the type-to-jump indicator (absolutely positioned, bottom-right). */
         position: relative;
+        /* The pane's single translucent base layer. `.content` is the only
+           ancestor that's mounted continuously across every dynamic state
+           (loading, error, MTP, file list, etc.), so painting it once here
+           guarantees a stable backdrop with no transition frame where the
+           vibrancy bleeds through. Downstream views (FullList / BriefList /
+           ErrorPane / …) keep their interior elements transparent so this
+           stays the single base layer — no doubling. Highlights (selection,
+           cursor) sit on top intentionally; their alpha is the tint, not a
+           second base layer. */
+        background-color: var(--color-bg-primary);
     }
 
     .error-message {
diff --git a/apps/desktop/src/lib/file-explorer/views/BriefList.svelte b/apps/desktop/src/lib/file-explorer/views/BriefList.svelte
@@ -974,6 +974,8 @@
         padding: var(--spacing-xxs) var(--spacing-sm);
         gap: var(--spacing-sm);
         align-items: center;
+        /* Rows are transparent; pane bg lives on `.file-pane > .content`.
+           See FullList.svelte / FilePane.svelte for the rationale. */
         white-space: nowrap;
         overflow: hidden;
     }
diff --git a/apps/desktop/src/lib/file-explorer/views/CLAUDE.md b/apps/desktop/src/lib/file-explorer/views/CLAUDE.md
@@ -69,16 +69,16 @@ compact/comfortable/spacious). The virtual scroll uses an `itemSize` parameter f
 
 **Decision**: `FullList`'s column header lives **inside** the scroll container as a `position: sticky; top: 0;` child,
 not as a sibling above. **Why**: when the user has "Always show scrollbars" set (System Settings → Appearance),
-non-overlay scrollbars steal a ~15 px gutter from the scroll container. A sibling header rendering at the wrapper's
-full width then misaligned with the data rows below. Moving the header inside makes it share the row content width
+non-overlay scrollbars steal a ~15 px gutter from the scroll container. A sibling header rendering at the wrapper's full
+width then misaligned with the data rows below. Moving the header inside makes it share the row content width
 automatically (and therefore the scrollbar gutter), so columns line up at every scrollbar mode without JS measurement.
 The trade-off is virtual-scroll math: row positions are now `headerHeight` pixels into the scrollable content, so
-`FullList` derives `spacerScrollTop = max(0, scrollTop - headerHeight)` and `rowAreaHeight = containerHeight -
-headerHeight` and feeds those into `calculateVirtualWindow` / `getScrollToPosition` / `firstVisibleGlobalIndex` /
-`lastVisibleGlobalIndex` / `getVisibleItemsCountUtil`. `scrollToIndex` adds `headerHeight` back when writing to
-`scrollContainer.scrollTop`. A11y: the listbox role moves off `.full-list` (now a generic scroll container) onto a
-`.listbox-region` inner wrapper around `.virtual-spacer` so the sticky header isn't a direct child of the listbox
-(would violate `aria-required-children`).
+`FullList` derives `spacerScrollTop = max(0, scrollTop - headerHeight)` and
+`rowAreaHeight = containerHeight - headerHeight` and feeds those into `calculateVirtualWindow` / `getScrollToPosition` /
+`firstVisibleGlobalIndex` / `lastVisibleGlobalIndex` / `getVisibleItemsCountUtil`. `scrollToIndex` adds `headerHeight`
+back when writing to `scrollContainer.scrollTop`. A11y: the listbox role moves off `.full-list` (now a generic scroll
+container) onto a `.listbox-region` inner wrapper around `.virtual-spacer` so the sticky header isn't a direct child of
+the listbox (would violate `aria-required-children`).
 
 **Decision**: Virtual scroll in frontend, data in backend **Why**: Sending 50k entries over IPC = 17.4MB, ~4s transfer.
 Virtual scroll fetches only visible ~50 items on demand. Backend-driven caching eliminates serialization overhead.
diff --git a/apps/desktop/src/lib/file-explorer/views/FullList.svelte b/apps/desktop/src/lib/file-explorer/views/FullList.svelte
@@ -896,9 +896,7 @@
             </div>
         </div>
         {#if (hasParent ? totalCount - 1 : totalCount) === 0}
-            <div class="empty-folder-message" style="height: {rowAreaHeight - (hasParent ? rowHeight : 0)}px;">
-                Empty folder
-            </div>
+            <div class="empty-folder-message">Empty folder</div>
         {/if}
         </div>
     </div>
@@ -952,11 +950,30 @@
     /* Semantic wrapper for the listbox role; no visual styling. The class
        exists so the role + aria-activedescendant can sit on a child of the
        scroll container without violating aria-required-children (the sticky
-       header is a sibling, not a child of this region). */
+       header is a sibling, not a child of this region).
+       `min-height: calc(100% - <header height>)` makes the listbox always
+       span the rest of the pane below the sticky header, even when there
+       are fewer rows than fit on screen — so the empty area is still part
+       of the listbox (for hit testing / focus) while staying transparent
+       (file rows paint the bg, not this wrapper). The header's own height
+       is `calc(22px * var(--font-scale))`, mirrored here so subtracting it
+       lands the listbox exactly flush with the scroll container's bottom
+       at every text scale, with no spurious scrollbar. */
+    /* Semantic listbox wrapper — no background, no stacking context. The
+       pane bg lives on `.file-pane > .content` (see FilePane.svelte). */
     .listbox-region {
         outline: none;
     }
 
+    .empty-folder-message {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        flex: 1;
+        color: var(--color-text-tertiary);
+        font-size: var(--font-size-sm);
+    }
+
     .virtual-window {
         will-change: transform;
     }
@@ -967,6 +984,12 @@
         padding: var(--spacing-xxs) var(--spacing-sm);
         gap: var(--spacing-sm);
         align-items: center;
+        /* Rows are transparent. The pane's base translucent layer lives on
+           `.file-pane > .content` (see FilePane.svelte) — painting it once
+           there is the single-source-of-truth approach: every pane pixel
+           gets exactly one base layer, never zero (no flicker on state
+           swap) and never two (no double-paint). Highlights (selection,
+           cursor) keep their own bgs and sit on top as intentional tints. */
         /* Guarantee one visual line per row regardless of cell content length */
         white-space: nowrap;
         transition: grid-template-columns 300ms ease;
@@ -1292,12 +1315,4 @@
         color: var(--color-text-primary);
     }
 
-    .empty-folder-message {
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        flex: 1;
-        color: var(--color-text-tertiary);
-        font-size: var(--font-size-sm);
-    }
 </style>
diff --git a/apps/desktop/src/lib/settings/settings-applier.ts b/apps/desktop/src/lib/settings/settings-applier.ts
@@ -59,6 +59,19 @@ function applyDateColors(palette: DateColorsPalette): void {
   log.debug('Applied date colors palette: {palette}', { palette })
 }
 
+/**
+ * Toggles the window's translucent (macOS `NSVisualEffectView` Sidebar
+ * material) backdrop by setting `data-translucency` on the root element.
+ * `app.css` scopes the opaque-bg fallback to `[data-translucency='off']`.
+ * The vibrancy material is configured statically in `tauri.conf.json` and
+ * stays alive behind the webview either way; when this is off, the CSS
+ * paints the webview's bg fully opaque so the material isn't visible.
+ */
+function applyTranslucency(enabled: boolean): void {
+  document.documentElement.dataset.translucency = enabled ? 'on' : 'off'
+  log.debug('Applied translucency: {enabled}', { enabled })
+}
+
 /**
  * Density currently has no CSS-side effect: `--spacing-icon-size` is owned
  * by `app.css` as `calc(16px * var(--font-scale))`, and row height /
@@ -131,6 +144,9 @@ function applyAllSettings(): void {
   // Date age color palette
   applyDateColors(getSetting('appearance.dateColors'))
 
+  // Translucency (macOS vibrancy backdrop)
+  applyTranslucency(getSetting('appearance.translucency'))
+
   // Theme (light / dark / system). Must run at startup or windows that open
   // before the user touches Settings will flash the wrong theme.
   void applyTheme(getSetting('theme.mode'))
@@ -185,6 +201,10 @@ function handleSettingChange(id: string, value: unknown): void {
     applyDateColors(value as DateColorsPalette)
     return
   }
+  if (id === 'appearance.translucency') {
+    applyTranslucency(value as boolean)
+    return
+  }
   if (id === 'theme.mode') {
     void applyTheme(value as ThemeMode)
     return
diff --git a/apps/desktop/src/lib/settings/settings-registry.ts b/apps/desktop/src/lib/settings/settings-registry.ts
@@ -61,6 +61,16 @@ export const settingsRegistry: SettingDefinition[] = [
       ],
     },
   },
+  {
+    id: 'appearance.translucency',
+    section: ['Appearance', 'Colors and formats'],
+    label: 'Translucency',
+    description: 'Liquid glass-y look if also enabled in your System Settings.',
+    keywords: ['translucency', 'translucent', 'vibrancy', 'glass', 'blur', 'transparency', 'liquid'],
+    type: 'boolean',
+    default: true,
+    component: 'switch',
+  },
   {
     id: 'appearance.sizeColors',
     section: ['Appearance', 'Colors and formats'],
diff --git a/apps/desktop/src/lib/settings/types.ts b/apps/desktop/src/lib/settings/types.ts
@@ -123,6 +123,7 @@ export type AiLocalContextSize = '2048' | '4096' | '8192' | '16384' | '32768' |
 export interface SettingsValues {
   // Appearance
   'appearance.appColor': AppColor
+  'appearance.translucency': boolean
   'appearance.textSize': number
   'appearance.uiDensity': UiDensity
   'appearance.useAppIconsForDocuments': boolean
diff --git a/apps/desktop/src/routes/(main)/+page.svelte b/apps/desktop/src/routes/(main)/+page.svelte

Original file line number	Diff line number	Diff line change
`@@ -974,6 +974,8 @@`
`974`	`974`	`padding: var(--spacing-xxs) var(--spacing-sm);`
`975`	`975`	`gap: var(--spacing-sm);`
`976`	`976`	`align-items: center;`
	`977`	+ /* Rows are transparent; pane bg lives on `.file-pane > .content`.
	`978`	`+ See FullList.svelte / FilePane.svelte for the rationale. */`
`977`	`979`	`white-space: nowrap;`
`978`	`980`	`overflow: hidden;`
`979`	`981`	`}`