Lynx Theme Pro Architecture: Themes, Icons, Liquid Glass

Lynx Theme Pro is a VS Code extension that ships 8 color themes, a 1,280+ SVG icon pack with three file/folder styles and two system icon sets, and an experimental Liquid Glass glassmorphism engine that injects CSS directly into the VS Code workbench. Seven of the eight themes are pure JSON files with zero runtime code; only the eighth — the LIQUID theme — requires a TypeScript compilation step and an Electron-side runtime injector. Understanding this split is the key to navigating the codebase confidently.

Project Structure

The repository layout below maps every significant directory and file to its purpose. The dist/ directory is gitignored and generated by the esbuild pipeline; the public/ directory contains marketing assets and translated READMEs that are excluded from the published VSIX bundle.

Lynx-Theme-Pro/
├── .vscode/                             # Editor workspace settings
├── src/
│   ├── themes/                          # 8 theme JSONs + Liquid (blur) engine
│   │   ├── 01_Lynx-Dark-theme.json
│   │   ├── 02_Lynx-Light-theme.json
│   │   ├── 03_Lynx-Night-theme.json
│   │   ├── 04_Lynx-Ghibli-theme.json
│   │   ├── 05_Lynx-Fury-theme.json
│   │   ├── 06_Lynx-Kiro-theme.json
│   │   ├── 07_Lynx-NVIM-theme.json
│   │   ├── 08_Lynx-Liquid-theme.json
│   │   └── liquid-theme/                # 🧪 Glassmorphism engine (TS)
│   │       ├── css/                     # Per-OS CSS patches
│   │       ├── platforms/               # OS detection & integration
│   │       ├── runtime/                 # Injection + activation
│   │       ├── utils/                   # Shared helpers
│   │       └── liquid-theme.ts          # Entry point
│   ├── icons/                           # Icon system (JSON configs)
│   │   ├── icon-system/                 # IDE chrome icons (material/test)
│   │   └── icon-themes/                 # File/folder icon themes
│   │       ├── lynx-icons-dark.json     # Style A — dark variant
│   │       ├── lynx-icons-light.json    # Style B — light variant
│   │       └── lynx-icons-gray.json     # Style C — gray variant
│   ├── assets/
│   │   ├── svg/                         # 1280+ SVG icon files
│   │   └── woff/                        # Font assets
│   ├── types/                           # Shared TypeScript types
│   └── __test__/                        # Unit tests
├── public/                              # Marketing & docs (excluded from VSIX)
│   ├── banner.webp                      # README banner
│   ├── docs/                            # Translated READMEs (11 languages)
│   │   └── README_AR / DE / ES / FR / HI / JA / KO / PT / RU / VI / ZH
│   └── github/
│       ├── icon/                        # Marketplace badges & icons
│       ├── images/                      # Marketing images
│       └── screenshots/                 # Theme & icon previews
├── dist/                                # esbuild output (gitignored)
├── .vscodeignore                        # Controls what ships in the VSIX bundle
├── AGENTS.md                            # Build commands & conventions
├── ARCHITECTURE.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── esbuild.js                           # Bundler config
├── eslint.config.mjs                    # Lint rules
├── package.json                         # Extension manifest & contributes
├── package.nls.json                     # Default UI strings (en)
├── package.nls.{ar,de,es,fr,hi,ja,ko,pt-br,ru,vi,zh-cn}.json   # i18n
└── tsconfig.json                        # TypeScript config

The 8 Themes

Seven of the eight themes are plain JSON files in src/themes/ — no compilation required. The eighth theme (LIQUID) is backed by a TypeScript engine described in the next section. VS Code reads each theme file directly from its path declared in package.json.

#	Theme	Type
1	DARK	Dark (`vs-dark`)
2	LIGHT	Light (`vs`)
3	NIGHT	Dark (`vs-dark`)
4	GHIBLI	Light (`vs`)
5	FURY	Dark (`vs-dark`)
6	KIRO	Dark (`vs-dark`)
7	NVIM	Dark (`vs-dark`)
8	LIQUID 🧪	Dark + Glass (`vs-dark`)

The numeric prefix in each filename (01_, 02_, …, 08_) is not decorative. VS Code sorts the theme picker alphabetically, so the prefixes guarantee a stable, predictable display order. Do not remove or reorder existing prefixes without updating all downstream references. Every theme JSON uses the same top-level schema:

{
  "$schema": "vscode://schemas/color-theme",
  "semanticClass": "theme.lynx.dark",
  "semanticHighlighting": true,
  "name": "1. DARK  (Lynx Theme)",
  "type": "dark",
  "colors": { ... },
  "tokenColors": [ ... ]
}

$schema — enables IntelliSense and validation in VS Code while editing the JSON.
semanticHighlighting — when true, VS Code applies language-server-driven semantic token colors on top of grammar-based highlighting.
colors — workbench UI colors (sidebar, tabs, status bar, editor background, etc.).
tokenColors — TextMate grammar rules for syntax token colors.

The Icon System

All icon configuration lives in src/icons/, split into two categories: icon-themes (file and folder icons visible in the Explorer) and icon-system (product icons used in VS Code’s own UI chrome). File/folder icon themes (src/icons/icon-themes/):

File	Style	Description
`lynx-icons-dark.json`	A	Original dark color variant
`lynx-icons-light.json`	B	Alternative light/modern aesthetic
`lynx-icons-gray.json`	C	Neutral gray variant

System icon themes (src/icons/icon-system/):

File	Label
`lynx-material-icon.json`	Lynx (Material) Icons
`lynx-test-icon.json`	Lynx (Test) Icons

All five configs draw from the same shared SVG pool at src/assets/svg/ (1,280+ files). Adding a single SVG there makes it available to every style — you only need to add the mapping in the JSON configs for the styles you want to update. Each icon config maps SVGs using these JSON keys:

{
  "fileExtensions": { "ts": "typescript-file" },
  "fileNames":      { "Dockerfile": "docker-file" },
  "languageIds":    { "rust": "rust-file" },
  "folderNames":    { "src": "src-folder" },
  "folderNamesExpanded": { "src": "src-folder-open" }
}

SVG filenames follow a consistent naming convention: name-file.svg, name-folder.svg, and name-folder-open.svg.

The Liquid Glass Engine

VS Code provides no native API for window-level transparency or blur effects, so the Liquid Glass engine achieves glassmorphism by injecting CSS directly into the workbench HTML. This is the only part of the extension that requires TypeScript compilation. Entry point: src/themes/liquid-theme/liquid-theme.ts → compiled to dist/themes/liquid-theme/liquid-theme.js. The activation flow is:

liquid-theme.ts (activate)
├── Detect OS via process.platform
│   ├── "linux"   → platforms/linux.ts
│   ├── "darwin"  → platforms/macos.ts
│   └── "win32"   → platforms/windows.ts
├── Check context.globalState key "lynxLiquidInstalled"
├── If Liquid theme is active → handleActivation(context)
│   └── Loads the platform-specific CSS patch
│       └── Injects CSS into the active workbench window
└── Listen for workbench.colorTheme changes
    ├── Theme switched TO Liquid  → handleActivation(context)
    └── Theme switched AWAY       → handleDeactivation(context)

Platform modules (src/themes/liquid-theme/platforms/): Each platform module exports handleActivation and handleDeactivation. They handle the OS-specific file paths to VS Code’s workbench HTML and apply the appropriate CSS template.

Module	Platform
`platforms/linux.ts`	Linux
`platforms/macos.ts`	macOS
`platforms/windows.ts`	Windows

Runtime injection (src/themes/liquid-theme/runtime/inject.mts): The inject.mts file runs inside VS Code’s Electron main process — not the extension host. This is necessary because writing to the workbench HTML requires elevated file access that the extension host sandbox does not permit. The file is compiled as an ESM .mjs module (see the esbuild section below). CSS templates (src/themes/liquid-theme/css/):

css/
├── animation/
│   └── text.css          # Text animation effects
├── blur/
│   └── blur.css          # Backdrop blur / frosted glass
├── liquid-glass/
│   └── liquid-glass.css  # Liquid glass panel styling
└── global.css            # Shared baseline styles

These CSS files are copied verbatim to dist/themes/liquid-theme/css/ after each build — they are not processed by esbuild. State persistence: The engine persists its install state using context.globalState.get('lynxLiquidInstalled', false). On startup, if the Liquid theme is not active and the state key is false, any leftover CSS residue is cleaned up automatically via cleanupLiquidResidue(context).

Patching the VS Code workbench HTML is unsupported by Microsoft and may trigger the “installation appears to be corrupt” cosmetic warning on startup. This is expected behavior — the extension functions normally despite this message. Microsoft may change workbench internals in any VS Code update, which could temporarily break the Liquid theme until the engine is updated.

The esbuild Pipeline

esbuild.js drives all compilation. It produces two separate output bundles from the same source tree, one for each execution context:

Output	Format	Extension	Source
Extension host	CJS	`.js`	`src/themes/liquid-theme/*/.ts` (excluding `runtime/`)
Electron runtime	ESM	`.mjs`	`src/themes/liquid-theme/runtime/*/.mts`

The extension host bundle uses CommonJS (format: 'cjs') because VS Code’s extension host runs in a Node.js CommonJS environment. The Electron runtime bundle uses ES modules (format: 'esm', outExtension: { '.js': '.mjs' }) because the Electron main process supports native ESM. After every successful build, the plugin automatically copies the contents of src/themes/liquid-theme/css/ to dist/themes/liquid-theme/css/. In production mode (--production), esbuild enables minification and disables source maps. In development mode, source maps are generated alongside each output file. Build commands and their recommended execution order:

npm run lint        # ESLint — run first to catch style issues early
npm run check-types # tsc --noEmit — type-check without emitting files
npm run compile     # Development build → dist/
npm run watch       # Watch mode — incremental rebuilds during development
npm run package     # Production build (minified, no source maps)

What VS Code Loads

package.json is the single source of truth for everything VS Code loads from this extension. It declares all extension contributions via the contributes key:

{
  "main": "./dist/themes/liquid-theme/liquid-theme.js",
  "activationEvents": ["onStartupFinished"],
  "contributes": {
    "themes": [
      { "label": "1. DARK  (Lynx Theme)",    "uiTheme": "vs-dark", "path": "./src/themes/01_Lynx-Dark-theme.json" },
      { "label": "2. LIGHT (Lynx Theme)",    "uiTheme": "vs",      "path": "./src/themes/02_Lynx-Light-theme.json" },
      { "label": "3. NIGHT (Lynx Theme)",    "uiTheme": "vs-dark", "path": "./src/themes/03_Lynx-Night-theme.json" },
      { "label": "4. GHIBLI (Lynx Theme)",   "uiTheme": "vs",      "path": "./src/themes/04_Lynx-Ghibli-theme.json" },
      { "label": "5. FURY  (Lynx Theme)",    "uiTheme": "vs-dark", "path": "./src/themes/05_Lynx-Fury-theme.json" },
      { "label": "6. KIRO  (Lynx Theme)",    "uiTheme": "vs-dark", "path": "./src/themes/06_Lynx-Kiro-theme.json" },
      { "label": "7. NVIM  (Lynx Theme)",    "uiTheme": "vs-dark", "path": "./src/themes/07_Lynx-NVIM-theme.json" },
      { "label": "8. LIQUID (Lynx Theme) 🧪","uiTheme": "vs-dark", "path": "./src/themes/08_Lynx-Liquid-theme.json" }
    ],
    "iconThemes": [
      { "id": "lynx-pro-dark",  "label": "Lynx Icons - (Style A)", "path": "./src/icons/icon-themes/lynx-icons-dark.json" },
      { "id": "lynx-pro-light", "label": "Lynx Icons - (Style B)", "path": "./src/icons/icon-themes/lynx-icons-light.json" },
      { "id": "lynx-pro-gray",  "label": "Lynx Icons - (Style C)", "path": "./src/icons/icon-themes/lynx-icons-gray.json" }
    ],
    "productIconThemes": [
      { "id": "lynx-test-icons",     "label": "Lynx (Test) Icons",     "path": "./src/icons/icon-system/lynx-test-icon.json" },
      { "id": "lynx-material-icons", "label": "Lynx (Material) Icons", "path": "./src/icons/icon-system/lynx-material-icon.json" }
    ]
  }
}

The extension activates on onStartupFinished and its main entry point is the compiled Liquid theme JS. All 7 static JSON themes require no activation — VS Code reads them directly from their declared paths. The .vscodeignore file ensures that public/ (screenshots, translated READMEs, marketing assets) and development configuration files are stripped from the VSIX bundle before publishing, keeping the package size minimal.

Companion Extensions

Lynx Theme Pro is part of a broader ecosystem of extensions maintained by Gohit X:

Extension	Purpose
ATM	Error Lens, Git Blame, Env Protection, screenshots
Lynx Keymap Pro	Unified keyboard shortcuts
Compare Code	Side-by-side code diffing

Get Started

Themes

Icons

Contributing

Lynx Theme Pro Architecture: Themes, Icons, Liquid Glass

Project Structure

The 8 Themes

The Icon System

The Liquid Glass Engine

The esbuild Pipeline

What VS Code Loads

Companion Extensions

Build docs developers (and LLMs) love

Get Started

Themes

Icons

Contributing

Documentation Index

​Project Structure

​The 8 Themes

​The Icon System

​The Liquid Glass Engine

​The esbuild Pipeline

​What VS Code Loads

​Companion Extensions

Build docs developers (and LLMs) love

Project Structure

The 8 Themes

The Icon System

The Liquid Glass Engine

The esbuild Pipeline

What VS Code Loads

Companion Extensions