Kawaii VS Code Color

Kawaii VS Code Color is a TypeScript-based VS Code theme extension with dark pink, dark contrast-tuned, light green pastel-pink, and light contrast-tuned themes, VS Code application settings, a custom Welcome page, optional modular Effects workbench styling, image-backed editor customization, Settings Sync support, and JSON import/export.

The current extension has grown into a standalone codebase with a compiled TypeScript extension host, typed settings/effects/welcome services, Settings and Welcome webviews, generated theme assets, local VSIX packaging, and automated unit, DOM, integration, package, and E2E validation.

Current Project

Release Notes

User-facing and maintainer release notes are tracked in CHANGELOG.md. The current release work focuses on bounded renderer observers, repeated Effects apply safety, generated workbench asset cleanup, copied image assets instead of injected image payloads, modular patch switches, public theme color packs, VS Code application settings defaults, Settings Sync / JSON bundle coverage, and the custom Welcome surface.

Preview

User Guide

Installation

Install from the Visual Studio Marketplace:

• Marketplace page: Kawaii VS Code Color
• Extension Name: Kawaii VS Code Color

Install from VS Code:

1. Open the Extensions view.
2. Search for Kawaii VS Code Color.
3. Select Install.

Install from the command line:

code --install-extension ITEM-PIXEL.kawaii-vscode-color

If you received a .vsix file:

1. Open the Extensions view.
2. Select Views and More Actions....
3. Select Install from VSIX....
4. Choose the .vsix file.

Setup

Enable the theme:

1. Open the Command Palette.
2. Run Preferences: Color Theme.
3. Select Dark Pink Kawaii, Kawaii Owl, Light Pink-Pastel Kawaii, or Kawaii heaven.

Open the extension settings:

1. Open the Command Palette.
2. Run Kawaii VS Code Color: Settings.
3. Use the side menu to switch between Home, Settings, Color Settings, Effects, Image Customization, Sync/Files, and Help.

The settings window opens as a normal editor tab.

Open the custom Welcome page:

1. Open the Command Palette.
2. Run Kawaii VS Code Color: Welcome.

The Welcome page opens as its own Kawaii Welcome editor tab. It is not the native VS Code Welcome page and is not embedded inside the Settings window.

Settings Window

The settings webview must use the active editor theme for its own UI. Its CSS consumes VS Code webview tokens such as --vscode-editor-background, --vscode-foreground, --vscode-button-background, and --vscode-panel-border; it must not define a separate hardcoded product palette for page surfaces, text, controls, panels, or states.

Welcome Window

The Welcome page uses images/kawaii-welcome-cat.png through a webview-safe URI and consumes VS Code webview tokens for its UI colors. Removing recent projects or files always asks for confirmation. Removed entries stay removed across reloads until the same project or file is opened again. Workspace expansion keeps the configured base tree visible and appends loaded child folders inline under the expanded folder instead of replacing the root list. The shared Search field filters loaded Workspace folders by name, path, or URI and keeps ancestor rows visible when a loaded descendant matches.

Implementation note for future SSH/Git work: the disabled SSH (upcoming) and Git (upcoming) menu entries already point to existing placeholder sections in src/welcomeWebview.ts (ssh-page and git-page). Re-enable and extend those sections when the features resume, reusing the current sidebar navigation and page switching structure instead of creating new duplicate pages.

Application Settings

On first activation in a VS Code profile, the extension applies these user-scope VS Code application defaults:

• Open the native VS Code Welcome page on startup.
• Show editor tabs as multiple tabs.
• Wrap editor tabs instead of scrolling.
• Open new project or folder selections in another window.

The first activation setup preserves the user's existing window.restoreWindows value. Its local marker is not registered for VS Code Settings Sync, so another synced machine/profile can run its own first-profile setup.

The Settings page reads the current VS Code values every time the settings UI opens. Saving from that page writes explicit user-scope VS Code settings for startup editor behavior, editor tab display, tab wrapping, new-folder window behavior, and session restore behavior.

The Settings page also exposes the Welcome workspace base path and Workspace tree depth at the top of Application Settings. These values are machine-local extension state, not part of Settings Sync or JSON export/import. The base path is used by the Welcome Workspace menu as the default location for folder selection and bounded folder browsing; when empty, the Welcome page falls back to c:/. The tree depth clamps inline expansion between 1 and 10 levels.

Color Settings

The Color Settings page edits local user overrides for the selected theme mode.

• Dark edits are written to [Dark Pink Kawaii] or [Kawaii Owl].
• Light edits are written to [Light Pink-Pastel Kawaii] or [Kawaii heaven].
• Existing settings under [Kawaii VS Code Color] and [Kawaii VS Code Color Light] are read as legacy aliases and migrated on the next write.
• Workbench colors are stored in workbench.colorCustomizations.
• Syntax colors are stored in editor.tokenColorCustomizations.
• Packaged theme source files are not modified.
• Workbench color rows include relationship info popovers generated from the theme color relationship database.
• Relationship popovers show related property color, relation direction, contrast preview, contrast percentage, and Good / Average / Poor quality.
• Default theme contrast analysis is precomputed during theme generation; customized colors are analyzed from the active values shown in the settings UI.
• Changing theme mode updates VS Code's native theme selection only; it does not refresh Kawaii Neon Effects or prompt a reload.

Use Reset to remove one custom color. Use Reset All to remove all color customizations for the selected theme mode.

Automatic theme data migration

Extension activation checks historical Kawaii theme labels before Settings or Welcome opens. Legacy dark/light labels and their workbench.colorCustomizations / editor.tokenColorCustomizations blocks are migrated to the current canonical labels at global and workspace scope. Existing canonical values win conflicts, while unique legacy properties and TextMate scopes are retained.

The migration creates a machine-local backup before its first configuration write, records the last recognized internal theme, and is idempotent on later starts. An unrelated active VS Code theme is never replaced merely because dormant Kawaii customization blocks exist. This update path does not apply Effects, patch workbench files, request a reload, or change generated theme sources.

Image Customization

The Image Customization page can store one editor background image and one no-tab logo replacement.

Supported image formats:

• PNG
• JPG/JPEG
• WEBP
• SVG

Images are capped at 2 MB. Settings previews use data: URLs and JSON exports carry base64 image payloads. Effects copy selected images into generated workbench asset files when effects are applied, but oversized images can still slow reloads; use a smaller image resolution if VS Code feels unstable.

Image changes do not auto-apply. Click Apply Effects, then reload VS Code when prompted. If the editor does not refresh cleanly, close and open VS Code manually.

Sync, Export, and Import

The settings bundle includes:

• VS Code application settings controlled by the Settings page.
• Active theme mode.
• Dark and light workbench color overrides.
• Dark and light token color overrides.
• Glow brightness and glow disable setting.
• Editor background image metadata, image bytes, opacity, and fit area.
• No-tab logo image metadata, image bytes, and opacity.

VS Code Settings Sync must be enabled in VS Code for Save to VSSync / Import VSSync to move data between machines.

Effects

VS Code color themes do not natively support text glow, editor background images, no-tab logo replacement, or arbitrary editor CSS. Those effects are provided by the optional Kawaii Neon runtime path.

Effects modify VS Code workbench files by adding one marked kawaii-vscode-colors-ui.js script reference with a refresh key. They write generated CSS and copied image assets next to the workbench HTML. That script adds the .kawaii-vscode-colors-ui class plus selected module classes to the highest workbench root, links the generated kawaii-vscode-colors-ui.min.css stylesheet, and emits scoped token glow rules when Glow Effects are enabled. The original VS Code token/style tags are not edited in place; the effect is additive and wrapper-conditioned.

The Effects stack has four independently selectable modules:

• Foundation / Runtime Layer: installs or removes the runtime wrapper script and shared stylesheet.
• Editor Background: applies the editor gradient, background image, opacity, and fit area.
• No-Page Logo: replaces the empty editor watermark logo when no tab is open.
• Glow Effects: applies syntax glow, active tab glow, activity indicators, and lightbulb styling.

Clicking Apply Effects cleans previous generated modifications and assets, then applies the selected module stack. All modules default to enabled.

Switching between Kawaii themes does not automatically refresh the injected Effects stack. Click Apply Effects only when you want to rewrite the workbench patch for the current settings.

Use it with caution:

• Administrator permissions may be required on Windows.
• VS Code may show an unsupported or corrupted installation warning.
• VS Code updates can overwrite the patch.
• Disable the effect before troubleshooting editor startup or workbench rendering issues; disabling removes the marked HTML reference and generated Kawaii JS/CSS/image assets.

Enable or disable the effect:

1. Run Kawaii VS Code Color: Settings.
2. Open Effects.
3. Use Enable Effects or Disable Effects.
4. Reload VS Code when prompted.

If VS Code shows the corruption warning, the Effects page includes the official VS Code FAQ link and an optional checksum-fix community workaround. The supported recovery path is to disable Effects and reinstall or repair VS Code so the modified workbench files are replaced.

VS Code Settings

Customize glow brightness:

{
  "kawaii_synthwave.brightness": 0.45
}

The value should be a number from 0 to 1. The default is 0.45.

Keep editor chrome updates but disable token glow:

{
  "kawaii_synthwave.disableGlow": true
}

After changing either setting, open Kawaii VS Code Color: Settings, apply Effects again, and reload VS Code.

Developer Guide

TypeScript Architecture

The extension runtime is compiled from TypeScript into out/src, and package.json.main points to ./out/src/extension.js.

Local Setup

Install project dependencies:

npm install

Validate the extension metadata and scripts:

npm pkg get name version publisher dependencies devDependencies engines
npm run test:check
npm run test:unit
npm run test:dom
npm run test:integration
npm run test:package
npm run test:e2e
npm run test:all
npm run update:themes -- --dry-run
npm run build:theme

Automated Tests

The project has four regular automated test layers, plus one gated Effects E2E layer:

Safety matrix:

The integration suite opens Kawaii VS Code Color: Settings and Kawaii VS Code Color: Welcome, but it does not control the rendered VS Code window. The safe E2E suite does control the real window and webviews, but it is still safe by default: it does not click Enable Effects, Disable Effects, or Apply Effects. Upload/import/export/download and Random Neko flows are covered only through explicit E2E fixture hooks, so no native OS dialog or external network request is used. E2E screenshots and state notes are written under test-results/e2e.

test-results/e2e/kawaii-last-run.json is the project-owned source of truth for the last npm run test:e2e, npm run test:e2e:current, or gated npm run test:e2e:neon execution. It records the mode, status, timings, exit code, disposable storage paths, Mocha phase configs, failed test ids when the current run fails, and key artifact paths. test-results/e2e/.last-run.json is an ExTester diagnostic file only and can be stale after later successful runs.

The safe E2E suite also writes Welcome screenshots and settings-visual-*.png screenshots plus settings-visual-state-analysis.json. Those artifacts cover Welcome navigation/removal confirmation/configure-help flows, Settings webview image previews, selected-image warnings, missing-image states, Random Neko loading presentation, effects warning, Effects status, error status, invalid color input, empty color filter, opacity value changes, editor background fit selector state, controlled fixture dialog flows, and color picker alpha persistence. The JSON file records programmatic PNG difference, color-ratio, or contrast metrics for each before/after visual assertion.

Visual test rule: tests should create screenshots only for behavior that changes a visible UI or theme state. When a visual state changes, keep before/after evidence, or a baseline/after pair, so the rendered result can be inspected alongside DOM/CSS assertions.

The real Effects patch has its own gated command:

$env:KAWAII_E2E_ALLOW_NEON_PATCH = "1"
npm run test:e2e:neon

npm run test:e2e:neon patches only the disposable VS Code installation under .vscode-test/extest-111-neon. The runner refuses Kawaii Neon mode unless KAWAII_E2E_ALLOW_NEON_PATCH=1 is present and the storage path resolves inside that disposable directory. It runs five separate VS Code launches to validate the same lifecycle users may need manually: before applying, after applying dstgroup images and reopening VS Code, after switching to an alternate image and reopening VS Code, after reverting to dstgroup and reopening VS Code, and after removing the patch and reopening VS Code. During the first launch it applies every Foundation / Runtime Layer, Editor Background, No-Page Logo, and Glow Effects switch combination, reloads the disposable workbench, captures before/after screenshots, validates generated HTML/JS/CSS/assets, validates runtime module classes, and writes test-results/e2e/neon-effects-combination-matrix.json. It verifies the workbench HTML hash returns to the original baseline and that injected runtime CSS uses editor-provided --vscode-* tokens rather than a standalone UI palette.

The gated Kawaii Neon suite imports controlled settings fixtures through internal test hooks exposed only when KAWAII_E2E_ALLOW_NEON_PATCH=1. Its first apply path validates every modular Effects combination through the real Settings webview before leaving the default all-on stack applied for the restart phases. It validates generated kawaii-vscode-colors-ui.js, enabled module class literals, generated CSS asset URLs, editor background opacity/fit, no-tab logo opacity, active no-page fallback selector, runtime style tags, screenshots, image replacement, dstgroup logo restoration, generated asset deletion after disable, and final HTML restoration. It also writes a visual editor-background fit matrix under test-results/e2e with a no-overlay baseline plus one screenshot for each supported fit area: full, top, bottom, left, right, top-left, top-right, bottom-left, and bottom-right.

Build a Local VSIX

Package the extension:

npm run build:local

Validate the package helper without changing package.json.version:

npm run test:package

Install the generated VSIX in VS Code:

code --install-extension .\dist\kawaii-vscode-color-<version>.vsix --force

For VS Code Insiders:

code-insiders --install-extension .\dist\kawaii-vscode-color-<version>.vsix --force

Theme Color Workflow

• Keep src/core-themes/kawaii_synthwave-color-theme.json as the protected dark base theme.
• Keep src/core-themes/kawaii_synthwave-color-theme-light.json as the protected light base theme.
• Put the default dark palette changes in themes/dark-pink-kawaii.json.
• Put dark contrast-tuned palette changes in themes/kawaii-owl.json.
• Put the default light palette changes in themes/light-pink-pastel-kawaii.json.
• Put light contrast-tuned palette changes in themes/kawaii-heaven.json.
• Keep every public color pack in themes/ as theme-id.json with non-null numeric version.major, version.minor, and version.patch.
• Run npm run update:themes -- --dry-run to validate the public GitHub themes folder without writing local files.
• Run npm run update:themes to download only missing packs or packs with a higher remote version.
• Run npm run build:theme to regenerate the native theme JSON files, internal catalog, relationship database, default contrast cache, and relationship docs under src/generated-themes and docs/theme-color-relationships.
• Run npm run docs:theme-colors after workbench colors keys change if you need to refresh only the property relationship tree, graph, tables, complete matrix, relationship database, and contrast cache from already generated themes.
• Run npm run docs:theme-colors:refresh-reference only when intentionally refreshing the official VS Code Theme Color reference snapshot used by that documentation.
• Run npm run test:theme-color-docs to verify the generated property matrix covers every generated workbench color property against every other property.
• VS Code loads generated themes through package.json.contributes.themes.

Manual Theme Test

1. Open this repository in VS Code.
2. Run npm run build:theme.
3. Press F5 to launch the Extension Development Host.
4. Select Dark Pink Kawaii, Kawaii Owl, Light Pink-Pastel Kawaii, or Kawaii heaven.
5. Inspect representative files and use Developer: Inspect Editor Tokens and Scopes for token rules.

Live Effects testing is possible from the Extension Development Host, but it patches the VS Code installation used by that host. Prefer a disposable VS Code installation or VS Code Insiders.

Publishing

Before publishing:

• Confirm package.json.publisher is ITEM-PIXEL.
• Confirm package.json.name is kawaii-vscode-color.
• Confirm package.json.repository.url points to the public repository that contains the README images.
• Confirm CHANGELOG.md has a release section for the package version being published.
• Package to ./dist with npm run build:local.
• Publish only from an account authorized for the configured publisher.

History

Kawaii VS Code Color is rewrited with Typescript and roots in SynthWave '84 - VS Code theme, It also extends with its own settings UI, persistence, generated assets, packaging flow, and test coverage. Historical README material and attribution details are preserved in README_LEGACY.md.

References

• Marketplace extension: Kawaii VS Code Color
• Repository: EmmiiChan/kawaii-vscode-color
• Changelog: CHANGELOG.md
• VS Code Color Theme guide: Color Theme
• VS Code Theme Color reference: Theme Color
• VS Code theme customization: Customize a color theme
• VS Code Settings Sync extension state: Common Capabilities - Data Storage
• VS Code extension manifest reference: Extension Manifest
• VS Code publishing guide: Publishing Extensions