vscode-backgrounds

Background art and a matching dark theme for VS Code, rendered from plain HTML — plus a worked-out account of how to make VS Code genuinely see-through on macOS, including the parts that break and how to put them back.

Two independent things live here, and you can take either one alone:

1. Ocean Aurora — a background image (generated from HTML, so it is editable as code) and a color theme built from the same palette.
2. Real window transparency — notes and a re-signing script for running Vibrancy Continued without leaving VS Code in a broken-signature state.

Warning

Part 2 patches the VS Code application bundle. That is reversible and its blast radius is VS Code alone (details in Real transparency), but it does break Microsoft's code signature until you re-seal it, and every VS Code update undoes the patch. If you only want the artwork and the theme, use part 1 and skip resign-vscode.sh entirely.

Quick start

Just the theme and background:

git clone https://github.com/kenjichristopherv-del/vscode-backgrounds.git
cd vscode-backgrounds
./deploy.sh

Then install the Background extension (shalldie.background), set workbench.colorTheme to "Ocean Aurora", and point background.fullscreen at ~/.vscode/extensions/.backgrounds/ocean-aurora-transparent.png. See How it works for why the image has to live in that directory.

Files

• ocean-aurora.source.html — the design source. Edit this to change the artwork.

• ocean-aurora.png — the rendered image (opaque, includes the dark ocean base).

• ocean-aurora-transparent.source.html — transparent variant: aurora + stars only, drawn per-pixel on canvas (CSS filter: blur() bands badly over a transparent backdrop in headless Chrome; gaussian falloff + dithering does not).

• ocean-aurora-transparent.png — the rendered transparent image (RGBA). The editor theme provides the dark base; this only paints light. Used by both background.fullscreen (whole window, so terminals opened as editor tabs get it too) and background.panel.

• deploy.sh — copies the PNGs to where VS Code is allowed to load them, and symlinks the theme extension into ~/.vscode/extensions/.

• resign-vscode.sh — re-seals the VS Code app bundle after vibrancy patching, so codesign --verify passes again. Run from Terminal.app, not VS Code's terminal.

• ocean-aurora-theme/ — a full VS Code color theme ("Ocean Aurora") built from the same palette as the artwork: #0B1021 ocean base with the five ribbon colors (#1DE9B6 mint, #536DFE indigo, #B388FF violet, #00B0FF cyan, #64FFDA teal) as UI accents, plus a Material-style syntax palette that matches the terminal ANSI colors.

• wallpaper-seethrough.source.html — takes a wallpaper.jpg sitting next to it and cover-fits it to the display with a contrast scrim, vignette, and a sub-pixel blur to hide the upscale. SCRIM / BLUR / VIGNETTE at the top of the source are the dials.

  Supply your own wallpaper.jpg. This repo does not ship one — drop a copy of your own desktop wallpaper in the repo root under that name and render it (see Workflow). Both wallpaper.jpg and the rendered wallpaper-seethrough.png are gitignored, so your image stays local and this repo never redistributes artwork it has no rights to. Swap the file and re-render whenever your wallpaper changes.

  This is only needed for the simulated transparency mode. The real-vibrancy mode shows the live desktop and needs no baked image at all.

How it works

The Background extension (shalldie.background) injects CSS into VS Code that paints the image behind the bottom panel (terminal, output, problems) at 30% opacity.

VS Code's internal vscode-file:// protocol only serves images from inside the app bundle or ~/.vscode/extensions/, so the deployed copy lives at:

~/.vscode/extensions/.backgrounds/ocean-aurora.png

Settings live in ~/Library/Application Support/Code/User/settings.json under background.fullscreen (whole-window overlay, 0.35) and background.panel (extra glow in the bottom panel, 0.3). There is no workbench.colorCustomizations block — the Ocean Aurora theme supplies the whole palette instead.

The theme lives in ocean-aurora-theme/ and is installed as a symlink at ~/.vscode/extensions/kenjitubera.ocean-aurora-theme-1.0.0, so edits to the theme JSON in this repo take effect on the next window reload. Select it with workbench.colorTheme: "Ocean Aurora" (or ⌘K ⌘T). The theme carries the terminal palette itself, so the old workbench.colorCustomizations block (21 entries) was removed rather than left to shadow it.

The see-through effect

VS Code cannot actually be transparent — Electron only supports it if the window is created with transparent: true, which VS Code does not expose (microsoft/vscode #12578 and #266530 were both closed as out-of-scope). So this simulates it: the wallpaper is baked into an image and painted inside the window.

Whether that image sits in front of or behind your text is what decides both how strong it can be and whether the text stays readable:

Target	Selector	Layer	Max opacity
background.editor	::before (useFront: false)	behind the code	none — uses style.opacity: 1
background.sidebar / panel / auxiliarybar	::after	in front of content	hard-capped at 0.6
background.fullscreen	body::after	in front of everything	hard-capped at 0.6

Only background.editor paints behind the text, so it is the one target that can run at full strength — and the extension additionally nulls .monaco-editor-background there, so the theme's editor color stops occluding the image. That is why the editor reads as genuinely see-through while the sidebar and panel sit at 0.30–0.35: on those, opacity is a direct tax on legibility.

Two overrides make it work, both passed through styles / style (arbitrary CSS, merged into a later rule on the same selector, so they beat the extension's own defaults — including the capped opacity):

• mix-blend-mode: normal — the extension forces screen (additive light, right for the aurora, wrong for a wallpaper, since screen can only brighten).
• background-attachment: fixed — positions each region's copy against the viewport instead of its own element, so the sidebar, editor, and panel each show their correct slice of one continuous image rather than three cropped copies.

The aurora stays on background.fullscreen at 0.35 with the default screen blend, so it glows over the wallpaper as light rather than replacing it.

workbench.colorCustomizations must NOT set terminal.background or panel.background to an opaque color — those override the theme and re-occlude the image. The theme now supplies all of it, so that block was removed.

Real transparency

The simulated mode above and this one are alternatives, not layers — pick one. Simulated is safe and reversible with a setting (background.enabled); this one is stronger and costs you a patched app bundle. Everything below is what that actually entails.

Actual see-through onto the live desktop — other windows included — comes from Vibrancy Continued (illixion.vscode-vibrancy-continued; the original EYHN.vscode-vibrancy was archived in 2022 and does not work past VS Code 1.57):

"vscode_vibrancy.theme": "Custom theme (use imports)",  // see below — do not change
"vscode_vibrancy.type": "transparent",   // clear glass; `under-window` = frosted
"vscode_vibrancy.opacity": 0,            // 0 = max transparency, 1 = opaque, -1 = theme default
"vscode_vibrancy.windowMode": "auto",    // frameless + transparent on macOS
"vscode_vibrancy.disableColorCustomizations": true,
"vscode_vibrancy.backgroundOverride": "#0B1021"

type: "transparent" is the only one of its 24 values that skips the blur — every other value is NSVisualEffectView vibrancy, i.e. frosted. There is no 0.6 clamp here.

disableColorCustomizations matters: left at its default the extension writes its own workbench.colorCustomizations and overrides the Ocean Aurora palette. Its disableThemeFixes stays at the default (fixes ON) — those patch VS Code internals that ignore alpha, which theme colors alone cannot reach.

vscode_vibrancy.theme is the non-obvious one, and leaving it unset silently reverts your color theme. On every activation the extension loads the config for whatever vscode_vibrancy.theme names (default "Default Dark" → themes/Default Dark.json), reads that file's colorTheme field ("Default Dark+", normalized to "Dark+"), and resets workbench.colorTheme to it on mismatch. That is what repeatedly knocked Ocean Aurora back to Dark+ — it looks like an external-edit race, so re-applying the setting never sticks. "Custom theme (use imports)" is the one value the check returns early on. It is safe: its Custom Theme.css is a one-line dummy, and the explicit settings above still win — type falls back to the theme config only when set to "auto", and opacity only when negative.

Commands are Enable Vibrancy / Disable Vibrancy / Reload Vibrancy (extension.installVibrancy / uninstallVibrancy / updateVibrancy).

This only shows through if the theme has an alpha channel, which is why Ocean Aurora sets editor, terminal, panel, and minimap backgrounds to #00000000 and the chrome (sidebar, activity bar, status bar, tabs) to ~45% tints. Floating surfaces — suggest widget, quick input, menus, notifications — deliberately stay near-opaque (F2/F7 alpha), because they can land over arbitrary desktop content and need their own contrast.

Costs, all real and all reversible:

• The "appears to be corrupt" warning. product.json carries a checksums map of 10 files, hashed as base64 SHA-256 (padding stripped) of out/<key>. Vibrancy modifies one of them, workbench.html — but only to add VscodeVibrancyContinued to the CSP trusted-types directive. Rehashing that file into product.json silences the warning. The actual runtime injection goes into out/main.js, which is not in the checksum map, so it never contributes.
• A CSP-only workbench.html is the normal working state. It has no injected <script> tag and looks half-patched; the runtime lives in out/main.js. To check whether vibrancy is really active, grep out/main.js for vibrancy — two appended lines, ~781. Inspecting the HTML gives a false negative.
• Every VS Code update overwrites the patch — F1 → Reload Vibrancy, restart, then re-run ./resign-vscode.sh.
• The code signature. Only the sealed resource manifest breaks; the executable is untouched and keeps Microsoft's TeamIdentifier UBF8T346G9 and hardened runtime, and every nested helper and framework still verifies. But codesign --verify fails on the outer bundle, and macOS consults it for TCC and Keychain — issue #266 reports Keychain re-prompting for logins. Microsoft's signature cannot be regenerated, so ./resign-vscode.sh re-seals ad-hoc instead: valid seal, no TeamIdentifier, and one round of re-approvals each time it runs.
• Blast radius is VS Code alone. No launch agents or daemons, nothing in /System, no kernel extensions. Everything lives in the app bundle plus ~/Library/Application Support/Code and ~/.vscode, both outside it — so the worst case is reinstalling VS Code, which costs nothing but the download.
• Battery is the cheap path. type: "transparent" maps to Electron backgroundMaterial: 'none', so there is no NSVisualEffectView compositing — the known Tahoe performance complaints are about the blur materials (acrylic, under-window). The patch method is overwrite (one-time write), not the interval variant, so no polling timer runs.
• Undo: F1 → Disable Vibrancy, or uninstall the extension.

Workflow

1. Edit a *.source.html

2. Render it to PNG. For the transparent variant:

   "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
     --headless=new --hide-scrollbars --default-background-color=00000000 \
     --window-size=2560,1440 --screenshot=ocean-aurora-transparent.png \
     "file://$PWD/ocean-aurora-transparent.source.html"
   

   For the wallpaper plate (needs file access for wallpaper.jpg):

   "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
     --headless=new --hide-scrollbars --allow-file-access-from-files \
     --virtual-time-budget=4000 --window-size=2560,1664 \
     --screenshot=wallpaper-seethrough.png \
     "file://$PWD/wallpaper-seethrough.source.html"
   

3. Run ./deploy.sh

4. Apply the patch: the extension does NOT re-patch on launch if a patch already exists — after a config change, either click "Apply and Reload" in its notification, or run "Background: Install" from the command palette (also reachable via the "Background" status-bar item). Editing only the image file (same path) needs just a window reload, since the patch stores the path.

Steps 3–4 apply to the simulated mode. If you are running the real-vibrancy mode instead, the Background extension is not involved — see the checksum note in Real transparency above for the corruption warning you will hit there.

License

Apache 2.0 — see LICENSE. Covers the code, the generated artwork, and the theme. It does not cover any wallpaper.jpg you supply; that stays yours (or its author's) and is never committed.