vscode-theme

name	vscode-theme
description	Generate VSCode color themes, package them as .vsix files, and install to VSCode. Use when creating custom VSCode themes, designing color schemes, or when the user mentions VSCode theme, color theme, dark theme, or light theme.

VSCode Theme Generator

Generate custom VSCode color themes from scratch, package them, and install them directly to VSCode.

Prerequisites

The following tools are required:

• @vscode/vsce (VSCode Extension Manager)
• code command (VSCode CLI)

Check if tools are installed:

which vsce || echo "vsce is not installed"
which code || echo "code command is not installed"

Install if missing:

# vsce
npm install -g @vscode/vsce

# code command: In VSCode, press Cmd+Shift+P → "Shell Command: Install 'code' command in PATH"

Theme Builder

This skill includes a theme builder script that enables efficient theme creation by editing individual part files.

Directory Structure

<theme-id>/
├── .vscodeignore          # Excludes parts/ and assets/ from .vsix
├── package.json           # Extension manifest
├── assets/
│   └── hero.png           # Hero banner (make-image) shown atop the README
├── parts/                 # Edit these files to customize
│   ├── base.json          # name, type, semanticHighlighting, description, colors
│   ├── colors-editor.json # Editor colors
│   ├── colors-ui.json     # UI colors (sidebar, tabs, etc.)
│   ├── colors-terminal.json # Terminal colors
│   ├── tokens.json        # Syntax highlighting
│   └── semantic.json      # Semantic token colors
└── themes/
    └── <theme-id>-color-theme.json  # Generated by merge

Builder Commands

# Initialize a new theme from template
npx tsx <skill-path>/theme-builder.ts init <theme-id> "<theme-name>" [--type dark|light]

# Merge parts into final theme file
npx tsx <skill-path>/theme-builder.ts merge <theme-id>

# Package as .vsix — delegates to `pnpm build`, which rebuilds ALL themes
# under themes/* (each gets README + hero + swatches + icon + CHANGELOG).
# The <theme-id> arg only selects which resulting .vsix path is returned.
npx tsx <skill-path>/theme-builder.ts package <theme-id>

# Bump version
npx tsx <skill-path>/theme-builder.ts bump <theme-id> [patch|minor|major]

Instructions

Step 1: Gather theme requirements

Ask the user for:

• Theme name (e.g., "Ocean Blue")
• Theme type: dark or light
• Color preferences (base colors, accent colors)
• Any specific style inspiration

Step 2: Initialize theme

npx tsx <skill-path>/theme-builder.ts init <theme-id> "<Theme Name>" --type dark

Replace:

• <skill-path>: Path to this skill directory
• <theme-id>: lowercase with hyphens (e.g., ocean-blue)
• <Theme Name>: display name (e.g., Ocean Blue)

Step 3: Edit part files

Edit the files in <theme-id>/parts/ to customize the theme.

parts/base.json

{
  "name": "Theme Name",
  "type": "dark",
  "semanticHighlighting": true,
  "description": "A short description of the theme's concept and visual style",
  "colors": ["#accent1", "#accent2", "#accent3", "#accent4", "#background"]
}

• description: Theme concept for the README (auto-generated; appears under the hero)
• colors: 5 representative hex colors rendered as shields.io color-swatch badges (filled with the hex, auto-contrasted text) in the README

parts/colors-editor.json

Editor-related colors:

Property	Description
editor.background	Main editor background
editor.foreground	Default text color
editorLineNumber.foreground	Line number color
editorCursor.foreground	Cursor color
editor.selectionBackground	Selection highlight
editorBracketMatch.*	Matching bracket highlight
editorError.foreground	Error underline
editorWarning.foreground	Warning underline

parts/colors-ui.json

UI element colors:

Property	Description
activityBar.background	Left sidebar icon bar
sideBar.background	File explorer background
statusBar.background	Bottom status bar
titleBar.activeBackground	Window title bar
tab.activeBackground	Active tab
tab.inactiveBackground	Inactive tabs
list.activeSelectionBackground	Selected item in lists
input.background	Input field background
button.background	Button background

parts/colors-terminal.json

Terminal colors including ANSI colors:

Property	Description
terminal.background	Terminal background
terminal.foreground	Terminal text
terminal.ansiBlack - terminal.ansiWhite	ANSI colors
terminal.ansiBrightBlack - terminal.ansiBrightWhite	Bright ANSI colors

parts/tokens.json

Syntax highlighting (array of token rules):

Scope	Applies to
comment	Comments
string	String literals
keyword	if, for, const, etc.
storage.type	Type keywords
entity.name.function	Function names
entity.name.type	Type/class names
variable	Variables
constant.numeric	Numbers
entity.name.tag	HTML/XML tags
entity.other.attribute-name	Attributes

Example token rule:

{
  "scope": ["comment", "punctuation.definition.comment"],
  "settings": { "foreground": "#6A9955", "fontStyle": "italic" }
}

parts/semantic.json

Semantic token colors (optional, object format):

{
  "function": "#DCDCAA",
  "variable.readonly": "#4FC1FF"
}

Step 4: Generate a hero image

Generate a hero/banner image that captures the theme's concept and save it to themes/<theme-id>/assets/hero.png. It appears at the top of the theme's README in the VSCode Extensions Details tab and in the repo's theme gallery.

Use the make-image skill (Codex CLI / gpt-image-2):

• Size: 1536x1024 (landscape banner)
• Prompt: tailor it to the theme's name, mood, and palette — pull the subject, setting, and dominant colors from base.json. A banner that matches the theme lands far better than a generic graphic.
• Garbled fake text in AI art is fine — just avoid prompts that require legible text.

Notes:

• The hero is referenced by its committed GitHub raw URL, so it renders in the Details tab only after the image is committed and pushed to main. Before push the link 404s — that is expected, not a bug.
• The build wires the hero in via existsSync: if assets/hero.png is absent, the README is generated without it (no broken-image link).
• assets/** is excluded from the .vsix (the README points at the raw URL), so the hero never bloats the package.

Step 5: Build and install

Detect which installation mode is active and use the appropriate command:

# Check if unified extension is installed
code --list-extensions | grep -q "custom.generald-themes"

• If unified is installed → pnpm run install-unified (rebuilds all themes as one extension, auto uninstalls old version first)
• If unified is NOT installed → pnpm run install-themes (builds and installs each theme individually)

Other available commands:

pnpm run build              # Build individual .vsix files (no install)
pnpm run build:unified      # Build unified .vsix (no install)
pnpm run uninstall-themes   # Uninstall individual themes
pnpm run uninstall-unified  # Uninstall unified theme

Every build (individual or unified) auto-generates each theme's README.md (Details tab — hero image + color-swatch palette + description), CHANGELOG.md, and icon from base.json and assets/hero.png. It also regenerates the repo's root README.md (theme gallery). Run pnpm readme to refresh only the root README.

Step 6: Offer to switch theme

After installation, ask the user if they want to switch to the new theme.

If yes, update the VSCode global settings:

# macOS
VSCODE_SETTINGS="$HOME/Library/Application Support/Code/User/settings.json"

Read the file, update "workbench.colorTheme" to the new theme's display name (from base.json), and write it back. Be careful to preserve the rest of the settings.

If no, just notify:

Theme installed successfully! Press Cmd+K Cmd+T (Mac) or Ctrl+K Ctrl+T (Windows/Linux) to select your new theme.

Color Design Tips

Dark themes

• Background: #1a1a2e to #2d2d44
• Foreground: #d4d4d4 to #eaeaea
• Limit accent colors to 1-2

Light themes

• Background: #ffffff to #f5f5f5
• Foreground: #1a1a1a to #333333
• Use muted accent colors

Transparency

Use alpha channel for subtle effects: #ffffff40 (last two digits = opacity 00-ff)

Accessibility

Aim for reasonable contrast between text and background for readability.

Troubleshooting

Theme not appearing

Run Developer: Reload Window from command palette.