feat(ui): enable windows mica effect by lacser · Pull Request #13476 · CherryHQ/cherry-studio

lacser · 2026-03-14T19:03:56Z

What this PR does

This PR enables Mica backdrop effect on Windows11.

Before this PR:

Previously, CherryStudio only supports window blur effect on MacOS.

After this PR:

Now, Mica effect is enabled for Windows. No CSS change is being made. Use following custom css to change transparency of ui components so that you can see mica effect.

CSS below is generated by Codex. I didn't review it. Use it for testing purpose only.

body[theme-mode='light'] {
  --navbar-background: rgba(244, 244, 244, 0);
  --navbar-background-mac: rgba(244, 244, 244, 0);

  --mica-surface-1: rgba(255, 255, 255, 0.42);
  --mica-surface-2: rgba(255, 255, 255, 0.56);
  --mica-surface-3: rgba(255, 255, 255, 0.68);
  --mica-border: rgba(255, 255, 255, 0.22);
}

body[theme-mode='dark'] {
  --navbar-background: rgba(22, 22, 22, 0);
  --navbar-background-mac: rgba(22, 22, 22, 0);

  --mica-surface-1: rgba(24, 24, 24, 0.42);
  --mica-surface-2: rgba(24, 24, 24, 0.56);
  --mica-surface-3: rgba(24, 24, 24, 0.68);
  --mica-border: rgba(255, 255, 255, 0.08);
}

/* Root transparency */
html,
body,
#root,
#root[style] {
  background: transparent !important;
  background-color: transparent !important;
  background-image: none !important;
}

/* Titlebar and window chrome: fully transparent, no mask */
#app-sidebar,
#app-sidebar[style],
.home-navbar,
.home-navbar[style],
[class*='NavbarContainer'],
[class*='NavbarMainContainer'],
[class*='NavbarHeaderContent'],
[class*='TabsBar'],
[class*='WindowControlsContainer'] {
  background: transparent !important;
  background-color: transparent !important;
  background-image: none !important;
  box-shadow: none !important;
  backdrop-filter: none !important;
  -webkit-backdrop-filter: none !important;
  border: none !important;
}

/* Remove the top-left titlebar mask feeling in left-navbar layout */
[navbar-position='left'] #content-container {
  border-top: none !important;
  border-left: none !important;
}

/* Main content shell: add stronger translucent mask */
#content-container,
#content-container[style],
[class*='TabContent'],
.home-tabs,
[class*='SettingContainer'],
[class*='MainContainer'],
[class*='ProgramSection'],
[class*='IconSection'] {
  background: var(--mica-surface-1) !important;
  background-color: var(--mica-surface-1) !important;
  box-shadow: none !important;
}

/* Slightly stronger mask for cards / groups / major panels */
[theme-mode='light'] #chat,
[theme-mode='light'] [class*='SettingGroup'],
[theme-mode='light'] [class*='AgentCardContainer'] {
  background: var(--mica-surface-2) !important;
  background-color: var(--mica-surface-2) !important;
  border: 1px solid var(--mica-border) !important;
}

[theme-mode='dark'] #chat,
[theme-mode='dark'] [class*='SettingGroup'],
[theme-mode='dark'] [class*='AgentCardContainer'] {
  background: var(--mica-surface-2) !important;
  background-color: var(--mica-surface-2) !important;
  border: 1px solid var(--mica-border) !important;
}

/* Input / editor area: a bit more solid for readability */
#inputbar,
.system-prompt,
[class*='CardContent'] {
  background: var(--mica-surface-3) !important;
  background-color: var(--mica-surface-3) !important;
  border: 1px solid var(--mica-border) !important;
}

/* Minapp drawer: keep readable, but remove titlebar mask */
.minapp-drawer .ant-drawer-header {
  background: transparent !important;
  background-color: transparent !important;
  border: none !important;
  box-shadow: none !important;
  backdrop-filter: none !important;
  -webkit-backdrop-filter: none !important;
}

.minapp-drawer .ant-drawer-body {
  background: var(--mica-surface-1) !important;
  background-color: var(--mica-surface-1) !important;
}

.minapp-drawer .minapp-mask {
  background: transparent !important;
}

Why we need it and why it was done in this way

The following tradeoffs were made:

No CSS change is made. This aligns with current implementation for MacOS. Even if window blur effect is currently enabled for MacOS, because the UI color is not transparent, the effect will not be visible unless you use a custom css. Below is a css I found for MacOS. https://github.com/hakadao/CherryStudio-Aero

Breaking changes

No breaking changes being made.

Special notes for your reviewer

Below are relevant docs
https://learn.microsoft.com/en-us/windows/win32/api/dwmapi/ne-dwmapi-dwm_systembackdrop_type
https://www.electronjs.org/zh/docs/latest/api/base-window#winsetbackgroundmaterialmaterial-windows

Checklist

This checklist is not enforcing, but it's a reminder of items that could be relevant to every PR.
Approvers are expected to review this list.

PR: The PR description is expressive enough and will help future contributors
Code: Write code that humans can understand and Keep it simple
Refactor: You have left the code cleaner than you found it (Boy Scout Rule)
Upgrade: Impact of this change on upgrade flows was considered and addressed if required
Documentation: A user-guide update was considered and is present (link) or not required. Check this only when the PR introduces or changes a user-facing feature or behavior.
Self-review: I have reviewed my own code (e.g., via /gh-pr-review, gh pr diff, or GitHub UI) before requesting review from others

Release note

Enable Mica Window backdrop effect. Supported on and above Windows 11 22H2.

Signed-off-by: Yaron <yaronching@outlook.com>

EurFelux

Not sure what does it look like because I use macOS. The code seems generally OK.

EurFelux · 2026-03-15T03:25:00Z

src/main/utils/windowUtil.ts

Could you add some test cases for getWindowsBackgroundMaterial?

isWindowsMicaSupported is never used by external module, so it should not be exported.

removed unnecessary export

Added some tests, not sure if they are necessary tho. I feel the main problem with current implementation is the way we get buildNumber is not very robust as @kangfenmao pointed out. But I didn't find a better way.

With that saying, worst case scenario, you simply lose Mica effect, nothing will break. Because:

...(windowsBackgroundMaterial ? { backgroundMaterial: windowsBackgroundMaterial } : {}), backgroundColor: mainWindowBackgroundColor,

EurFelux · 2026-03-15T03:29:01Z

src/main/services/WindowService.ts

          }),
-      backgroundColor: isMac ? undefined : nativeTheme.shouldUseDarkColors ? '#181818' : '#FFFFFF',
+      ...(windowsBackgroundMaterial ? { backgroundMaterial: windowsBackgroundMaterial } : {}),
+      backgroundColor: mainWindowBackgroundColor,


Should use consistent pattern like L91

There will be 3 nested ternary operator if we choose to use it. Three conditions are !isMac, !windowsBackgroundMaterial, nativeTheme.shouldUseDarkColors.
Which is bad readability.

Or maybe you want to use an inline defined function?

backgroundColor: (() => { if (!isMac && !windowsBackgroundMaterial) { return nativeTheme.shouldUseDarkColors ? '#181818' : '#FFFFFF' } return undefined })(),

Suggested change

backgroundColor: mainWindowBackgroundColor,

backgroundColor: ...(mainWindowBackgroundColor ? { backgroundColor: mainWindowBackgroundColor }),

before this PR, it was

backgroundColor: isMac ? undefined : nativeTheme.shouldUseDarkColors ? '#181818' : '#FFFFFF',

I didn't intend to change this. But sure, fixed now.

kangfenmao

✅ LGTM - Clean implementation following macOS blur pattern. The version gating logic is appropriate for this feature.

One small suggestion for the version parsing:

This handles edge cases more robustly if the version format varies.

Signed-off-by: Yaron <yaronching@outlook.com>

EurFelux

LGTM! Clean implementation following the existing macOS vibrancy pattern. One minor nit about version parsing for future-proofing, but not blocking.

EurFelux · 2026-03-15T05:13:03Z

src/main/utils/windowUtil.ts

+  const systemVersion = process.getSystemVersion()
+  const buildNumber = Number.parseInt(systemVersion.split('.')[2] ?? '', 10)
+
+  return Number.isFinite(buildNumber) && buildNumber >= WINDOWS_11_22H2_BUILD


nit: Only checking the build number while ignoring major.minor is not fully future-proof. Currently all Windows 11 versions use 10.0.xxxxx so this works fine in practice, but if a future Windows version ever changes the major version and decrease build number, this check would incorrectly disable Mica.

A more defensive approach would be to compare the full version tuple:

Suggested change

const systemVersion = process.getSystemVersion()

const buildNumber = Number.parseInt(systemVersion.split('.')[2] ?? '', 10)

return Number.isFinite(buildNumber) && buildNumber >= WINDOWS_11_22H2_BUILD

const systemVersion = process.getSystemVersion()

const [major, minor, build] = systemVersion.split('.').map(Number)

if ([major, minor, build].some((n) => !Number.isFinite(n))) return false

// Windows 10.0.22621+ supports Mica; future major versions (11.x+) are assumed to support it too

return major > 10 || (major === 10 && minor > 0) || (major === 10 && minor === 0 && build >= WINDOWS_11_22H2_BUILD)

Not blocking — totally fine to keep as-is given Microsoft's current versioning.

lacser added 2 commits March 14, 2026 14:16

feat: add mica background effect on windows

f766e31

Signed-off-by: Yaron <yaronching@outlook.com>

Merge remote-tracking branch 'origin/main' into feat/windows-mica

f01616f

lacser changed the title ~~Feat/enable windows mica effect~~ feat/enable windows mica effect Mar 14, 2026

lacser changed the title ~~feat/enable windows mica effect~~ feat(ui): enable windows mica effect Mar 14, 2026

EurFelux reviewed Mar 15, 2026

View reviewed changes

This comment was marked as duplicate.

Sign in to view

kangfenmao reviewed Mar 15, 2026

View reviewed changes

This comment was marked as resolved.

Sign in to view

lacser added 3 commits March 15, 2026 00:13

fix: removed unnecessary export

a45f13f

Signed-off-by: Yaron <yaronching@outlook.com>

test: add test cases for getWindowsBackgroundMaterial

c44d5e9

Signed-off-by: Yaron <yaronching@outlook.com>

fix: code style

92ec3c7

Signed-off-by: Yaron <yaronching@outlook.com>

EurFelux approved these changes Mar 15, 2026

View reviewed changes

EurFelux merged commit 19bd2cd into CherryHQ:main Mar 15, 2026
11 checks passed

	backgroundColor: mainWindowBackgroundColor,
	backgroundColor: ...(mainWindowBackgroundColor ? { backgroundColor: mainWindowBackgroundColor }),

Conversation

lacser commented Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does

Why we need it and why it was done in this way

Breaking changes

Special notes for your reviewer

Checklist

Release note

Uh oh!

EurFelux left a comment

Choose a reason for hiding this comment

Uh oh!

EurFelux Mar 15, 2026

Choose a reason for hiding this comment

Uh oh!

lacser Mar 15, 2026

Choose a reason for hiding this comment

Uh oh!

lacser Mar 15, 2026

Choose a reason for hiding this comment

Uh oh!

EurFelux Mar 15, 2026

Choose a reason for hiding this comment

Uh oh!

lacser Mar 15, 2026

Choose a reason for hiding this comment

Uh oh!

EurFelux Mar 15, 2026

Choose a reason for hiding this comment

Uh oh!

lacser Mar 15, 2026

Choose a reason for hiding this comment

Uh oh!

This comment was marked as duplicate.

Uh oh!

This comment was marked as duplicate.

Uh oh!

kangfenmao left a comment

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

EurFelux left a comment

Choose a reason for hiding this comment

Uh oh!

EurFelux Mar 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lacser commented Mar 14, 2026 •

edited

Loading

EurFelux Mar 15, 2026 •

edited

Loading