From Zero to Your First VS Code Theme: A Complete Beginner's Guide

Series Navigation

– Part 1: From Zero to Your First VS Code Theme (this article)

– Part 2: Stop Hand-Editing JSON: Engineering Your Theme with YAML (coming soon)

– Part 3: Light, Dark, and Beyond: Building Multi‑theme Variants (coming soon)

– Part 4: From Theme to Design System: Visual Contracts and Brand Ecosystems (coming soon)

If you have basic programming knowledge (familiar with JavaScript, JSON, and the command line) but have no idea how to turn your color palette into a VS Code theme, this article is for you.

Last year I designed a color scheme called Moongate for my personal blog—minimalist and sci‑fi inspired. Recently I thought: why not turn it into a VS Code theme? After a few days of exploration, I successfully published it. Here I’ve broken down the entire process into clear steps to help you avoid common pitfalls.

---

1. Prerequisites

Make sure you have installed:

• Node.js (includes npm)
• Git (optional, but recommended)

Then install Yeoman and the VS Code Extension Generator globally:

npm install -g yo generator-code

---

2. Generate the Theme Project

yo code

Follow the prompts:

1. New Color Theme
2. No, start fresh (don't import an existing theme)
3. Fill in the information:
   • Extension name: your theme name (e.g., moongate-theme)
   • Description: short intro, e.g., 🌙 Where Moon Meets Code – Minimalist Sci‑Fi Theme
   • Publisher name: your publisher ID (you'll need to register on the VS Code Marketplace later; for now you can use a placeholder like your-name and update package.json later)
4. Choose a base theme: Dark or Light
5. Theme display name: e.g., Moongate Dark

The generator will create a project folder with this structure:

your-theme/
├── themes/
│   └── your-theme-color-theme.json
├── package.json
├── README.md
├── CHANGELOG.md
└── ...

---

3. Core Concepts: colors and tokenColors

The theme configuration file lives in themes/. It consists of two main parts:

• colors: defines UI colors of the editor (title bar, status bar, sidebar, etc.)
• tokenColors: defines syntax highlighting for code (keywords, strings, comments, etc.)

🔍 How to Find the Correct Color Keys

VS Code provides two super handy tools:

1. UI Colors: Press Ctrl+Shift+P, run Developer: Generate Color Theme From Current Settings. This command outputs a JSON containing all UI color keys used by the current theme. You can copy the keys you need (like editor.background) directly – no manual lookup required.

2. Syntax Scopes: Open a code file, place your cursor on the element you want to color, and run Developer: Inspect Editor Tokens and Scopes. A popup will show the TextMate scopes list for that element. Choose the most specific one to use in your tokenColors rules.

🎨 Configuration Example

"colors": {
  "editor.background": "#0f172a",
  "editor.foreground": "#e2e8f0",
  "statusBar.background": "#0f172a"
  // ... more UI keys
},
"tokenColors": [
  {
    "name": "Comment",
    "scope": ["comment", "punctuation.definition.comment"],
    "settings": {
      "fontStyle": "italic",
      "foreground": "#94a3b8"
    }
  },
  {
    "name": "Keyword",
    "scope": ["keyword", "storage.type", "storage.modifier"],
    "settings": {
      "foreground": "#3b82f6",
      "fontStyle": "bold"
    }
  }
  // ... other rules
]

Note: The order of the tokenColors array matters—later rules override earlier ones with the same scope.

---

4. Local Debugging

1. Open your project folder in VS Code.
2. Press F5 to launch the Extension Development Host window.
3. In the new window, press Ctrl+K Ctrl+T and select your theme.
4. Open a test code file to see the theme in action.
5. Modify the theme JSON; in the development host, press Ctrl+R to reload and see changes immediately.

🔧 Debugging Tip: Master the Inspect Tool

When a syntax element isn't colored correctly, use Developer: Inspect Editor Tokens and Scopes to locate it. The popup tells you which rule is currently applying the color and lists the available scope chain. Always prefer the most specific scope to avoid affecting unrelated elements.

---

5. Polish the Details

1. Status Bar, Title Bar, etc.

Don't forget to configure these areas. Use the keys from the generated JSON as reference.

2. Contrast

Use tools to check that text contrast meets WCAG requirements (≥4.5:1 for normal text).

3. Semantic Highlighting (Advanced)

VS Code supports semantic highlighting, which colors tokens based on their semantic meaning (e.g., read‑only variables, function declarations) rather than simple syntax rules.

To enable semantic highlighting in your theme, you need to set "semanticHighlighting": true in package.json and provide a semanticTokenColors object in your theme file.

Example:

"semanticTokenColors": {
  "variable.readonly": {
    "foreground": "#cbd5e1",
    "fontStyle": "italic"
  },
  "function.declaration": {
    "foreground": "#7dd3fc",
    "fontStyle": "bold"
  },
  "parameter": {
    "foreground": "#cbd5e1",
    "fontStyle": "italic"
  }
}

This is the core of the Visual Depth philosophy—letting less important elements recede and important ones stand out, improving code readability.

---

6. Prepare for Publishing

1. Complete package.json

Essential fields in package.json:

{
  "name": "your-theme-name",
  "displayName": "Your Theme Display Name",
  "description": "Short description",
  "version": "1.0.0",
  "publisher": "your-publisher-id",
  "engines": { "vscode": "^1.109.0" },
  "categories": ["Themes"],
  "icon": "images/icon.png", // 128x128 PNG, make sure the path is correct
  "repository": {
    // optional but recommended
    "type": "git",
    "url": "https://github.com/yourname/your-theme"
  }
}

2. Prepare Screenshots

Create an images folder in the root and add at least 3‑5 code screenshots in different languages (1280×640 is recommended) for your README.

3. Write a README.md

Include the theme name, preview images, design philosophy, installation instructions, and optionally a color table.

4. Add a License

Use the MIT license—create a LICENSE file.

5. Create a .vscodeignore

Exclude unnecessary files, for example:

.vscode/**
.gitignore
node_modules

Important: Do not exclude the images/ folder, otherwise the screenshots won't be included in the packaged extension.

---

Pre‑Publishing Checklist

Before running vsce package, take two minutes to verify the following—this will save you from most common publishing errors:

• package.json information: Ensure publisher, name, and version are correct (publisher must exactly match the ID you registered on the marketplace).
• Icon file: Confirm the icon path points to a 128×128 PNG and that the file actually exists there.
• Preview images: Check that your README.md contains at least one theme preview (preferably from the images/ folder). A theme without previews is hard to attract users.
• .vscodeignore configuration: Verify that you've excluded unnecessary files (like .vscode, node_modules, src, etc.) but kept the images/ folder.
• Local packaging test: Run vsce package – if it successfully generates a .vsix file, your configuration is basically correct. If it fails, read the error message carefully; the most common culprits are a wrong icon path or a missing publisher.

Once everything is checked, you're ready to publish. If you encounter difficulties with the command line, you can also upload the .vsix file manually (see next section).

---

7. Package and Publish

1. Install Publishing Tool

npm install -g @vscode/vsce

2. Test Packaging

vsce package

If successful, a .vsix file will be generated. You can drag it into VS Code to test the installation manually. If it fails, read the error message—common issues are a wrong icon path or accidentally excluding necessary files in .vscodeignore.

3. Get a Personal Access Token

• Log in to Azure DevOps using the Microsoft account you used to register on the marketplace.
• Click your avatar in the top right → Personal access tokens → New Token.
• Give it a name, choose All accessible organizations, and set an expiration (1 year is fine).
• Permissions: Check only Marketplace → Manage (uncheck everything else).
• After creation, copy the token immediately (it's shown only once).

4. Log In and Publish

vsce login your-publisher-id
# Paste the token (it won't be visible, just press Enter)

vsce publish

The theme will be uploaded within seconds. It will appear in the VS Code Marketplace after about 5‑10 minutes.

Common Publishing Errors:

• Token verification failed: permissions not set correctly or token expired – generate a new one.
• Version already exists: update the version in package.json.
• Network issues: try a different network or use a proxy.

🔁 Alternative: Manual Upload

If you run into trouble with the command line, you can upload the .vsix file manually:

1. Make sure you have successfully generated the .vsix file with vsce package.
2. Go to the VS Code Marketplace management page and log in with your Microsoft account.
3. Click on your publisher name, then the Publish extension button in the top right.
4. Select your .vsix file and upload.
5. In a few minutes your theme will be live.

Pros: Bypasses command‑line token issues and is completely visual.

---

8. After Publishing

• View your marketplace page: https://marketplace.visualstudio.com/items?itemName=your-publisher-id.your-theme-name
• Log in to the Marketplace management dashboard to see stats (page views, installs, conversion).
• Add README badges (e.g., version, downloads) to your GitHub repo.
• Collect feedback and plan future updates.

🌟 Advanced: Create Your Visual Contract

The user's experience can vary drastically depending on their display settings. To ensure your theme looks as intended on different screens, consider providing a display calibration guide (we call it the Visual Contract in the Moongate series). Help users adjust brightness, contrast, and turn off “enhancement” features. This not only shows responsibility but also reflects professional brand spirit.

You can place this guide in an extras/ folder and recommend it in your README.

This is just a start; the full brand system (including the Visual Contract and Protocol Index) is expanded in the final part of the series.

---

9. Design Philosophy: From Looks Good to Works Well

Many beginners think a theme is just about picking nice colors. But a truly great theme makes the structure of the code emerge by itself. That’s the idea behind Visual Depth:

• Operators and punctuation should recede (lower brightness) so they don't distract.
• Function names should stand out (higher brightness) as visual anchors.
• Read‑only variables can use italics to hint at immutability.
• Deprecated code can have a strikethrough for instant recognition.

You can apply these principles to your own palette, turning code from something you look at into something you read.

---

10. A Tip: Leverage AI for Efficiency

As a solo developer, you may find that there are many details to polish—from the color scheme to syntax rules. AI can be a powerful assistant. Whether it's generating a starting tokenColors template, debugging a tricky scope, or writing documentation and translating your README, AI can provide solutions in seconds, saving you hours.

But remember: AI is a tool, not a decision‑maker. The final aesthetic judgment and design philosophy must be your own. That uniqueness is what AI cannot replace.

---

Final Words

Turning your personal color palette into a shareable VS Code theme is not complicated. The core is understanding the colors and tokenColors structures and making good use of VS Code's built‑in developer tools. When stuck, read error messages carefully and consult the official docs. If one approach fails, try another—just like the manual upload alternative, there’s always a way.

If you create your own theme, feel free to share it. In this vast code world, there will always be someone who loves the same moonlight as you.

---

This article is part of a series. The original Chinese version is available on my blog: moongate.top.

**Try the theme: Moongate Theme on VS Code Marketplace

**Star on GitHub: GitHub Repo

© 2026 yuelinghuashu. This work is licensed under CC BY-NC 4.0.