DEV Community: yuelinghuashu

From Theme to Design System: Visual Contracts and Brand Ecosystems

yuelinghuashu — Sat, 04 Apr 2026 13:42:34 +0000

🌕 Introduction: From Engineering to a Design System

In the first three parts, we built a solid engineering foundation for the Moongate theme: from monolithic JSON to modular YAML, from a single dark theme to both light and dark, from manual maintenance to a one‑click build script. Now we have an efficient, extensible theme production system.

But that’s not enough. A truly outstanding theme should not be just a collection of color rules. It should be a complete design system – one that includes a clear design philosophy, reusable visual language, a contract with the user, and a protocol that connects content with brand.

This part will take you from engineering to design system. Moongate will become more than a theme – it will be an industrial‑grade design system with DTCG design tokens, an elevation system, a visual contract, and automatically generated cross‑platform assets.

🎨 Part 1: Design Philosophy – Giving Every Color a Meaning

Every design system must be built on a clear design philosophy. Without it, colors are just random choices; with it, they become a brand identity.

1.1 Cool‑Based Foundation: Eliminating Visual “Dirt”

General principle: Add a subtle cool bias (blue or green) to backgrounds, borders, and grays. Pure black makes highlight colors “bleed”, and pure white can look yellowish or grayish. A hint of cool tone keeps the canvas clean and deep, allowing semantic colors to appear pure.

Moongate implementation:

Dark background: #0f172a (Deep Space blue‑black)
Light background: #f9fafb (Cool Moonlight)

1.2 Semantic Layering: The Three Tiers of Information

General principle: Code is not flat; it has natural hierarchy. Divide all code elements into three visual tiers – Foreground (core logic), Midground (regular code), and Background (auxiliary information). Use contrast, saturation, and font styles (bold, italic) to distinguish them, allowing the code structure to naturally “emerge”.

Moongate implementation:

Tier	Role	Visual Characteristics	Examples
Foreground	Core logic	High contrast, bold, or high saturation	Keywords, function definitions, class names
Midground	Regular code	Medium contrast, natural feel	Variables, strings, numbers
Background	Auxiliary information	Low contrast but readable	Comments, punctuation, operators

This layering applies to all languages and theme variants. It is the foundation of Moongate’s visual consistency.

1.3 Gravity Compensation: Visual Weight Parity Between Day and Night

General principle: A light theme is not simply the inverse of a dark theme. A bright color on a dark background acts like a “light source”; a dark color on a light background acts like an “absorber”. To give the same semantic role equal visual weight across backgrounds, keep the hue unchanged and scientifically adjust lightness and saturation. This is called Gravity Compensation.

Moongate implementation:

Semantic Role	Dark Theme	Light Theme	Adjustment
primary	`#3b82f6` (60% lightness)	`#0284c7` (48% lightness)	Hue unchanged, lightness reduced ~20%
success	`#34d399` (65%)	`#059669` (40%)	Lightness reduced, saturation slightly lowered
warning	`#fbbf24` (75%)	`#b45309` (35%)	From bright yellow to orange‑yellow
error	`#f87171` (60%)	`#b91c1c` (35%)	Deep red maintains warning character

When users switch themes, the visual weight of the same syntax element remains nearly unchanged – no re‑learning needed.

1.4 Elevation System: Giving the UI Physical Depth

General principle: Define multiple background lightness steps to express the physical depth of UI elements. In dark mode, higher elevation means brighter surfaces (lightness increases). In light mode, higher elevation also means brighter surfaces (using brighter whites or light colors). Step increments should be consistent (e.g., +5% lightness per step in dark mode, -3% in light mode) to create a smooth sense of layering.

Moongate implementation (v2.2.0):

Elevation Level	Use Case	Dark Mode	Light Mode	Lightness Change
`surfaceGround`	Base background	`#0f172a`	`#f9fafb`	Base layer
`surfaceRaised`	Sidebar, activity bar	`#131c31`	`#ffffff`	Dark: +5%, Light: pure white
`surfaceFloating`	Panels, floating cards	`#1e293b`	`#f1f5f9`	Dark another +5%, light gray‑blue
`surfaceTooltip`	Tooltips, popups	`#252e40`	`#e2e8f0`	Highest layer

This design makes the sidebar feel slightly raised, popups float, and the editor area sink deep – the editor moves from flat to physical, making the interface hierarchy obvious at a glance.

🔷 Part 2: DTCG Design Tokens – Turning Colors into Engineering Assets

General principle: Adopt the industry‑standard DTCG (Design Tokens Community Group) three‑layer architecture to upgrade color management from scattered variables to an engineering system:

Primitives layer: Hue‑based raw values (e.g., blue-500)
Semantics layer: Semantic roles that reference primitives (e.g., primary: "{blue-500}")
Components layer: Direct UI element mapping (e.g., sideBar.background: "${surfaceGround}")

This separation makes color changes predictable: adjust a primitive, and all semantics that reference it update automatically; change a semantic, and all UI components sync.

Moongate implementation: v2.2.0 fully implements the DTCG architecture. The build script automatically produces:

moongate-colors.css – CSS variables for all semantic colors in both light and dark modes, ready for blogs and UI component libraries.
moongate-layout.css – Layout tokens including spacing, radius, shadow, typography, breakpoints, and z‑index.
DESIGN_SYSTEM.md – A complete design system document with color swatches, elevation system explanation, semantic layer contrast data, and the Variable Selection Protocol – the “constitution” of the design system.

Industrial‑Grade Quality Checks

General principle: The build process should include multiple built‑in quality checks to ensure design system reliability:

Color normalization (expand shorthand, validate illegal values)
Circular reference detection (fail and output the reference chain if nesting exceeds depth limits)
Opacity safety net (prevent double‑applied opacity)
WCAG contrast checking (stop the build if the ratio falls below AA standards)

Moongate implementation: The build script implements all of the above quality checks, making Moongate a self‑validating design system.

📄 Part 3: Visual Contract – Connecting the User and the Hardware

General principle: No matter how well a theme is designed, it won’t look right on an uncalibrated display. Provide a display calibration guide (Visual Contract) to help users adjust gamma, brightness, contrast, and color temperature, and remind them to turn off “enhancements” like dynamic contrast or vivid mode. The goal of calibration is not theoretical perfection, but finding the most comfortable balance for each user.

Moongate implementation: Moongate provides a detailed Visual Contract document with the following core steps:

Step	Action	Goal
1. Set Gamma	Choose `Gamma 2.2` (Windows/macOS standard)	Smooth grayscale transitions
2. Adjust Brightness	Dark mode: make the 2% gray block barely visible; Light mode: make the 250–255 white blocks distinguishable	Preserve shadow and highlight details
3. Adjust Contrast	Make the 100% white block clear but not glaring	Avoid overexposure
4. Color Temperature	Recommend `6500K` or `Warm` mode	Neutralize blue light

It also lists common monitor‑specific pitfalls (black stabilizer, vivid mode, sharpness too high) and their solutions.

🔷 Part 4: Protocol Index – Turning Content into Assets

General principle: Blog content can be classified by technical depth (e.g., P1–P5). Each level corresponds to a typical technical depth and reader capability. The classification should be based on technical depth, not code volume, helping readers quickly judge whether an article suits them. This classification turns blog content into indexable engineering assets, complementing code assets.

Moongate implementation: The Moongate blog uses the P1–P5 Protocol:

Level	Core Definition	Typical Characteristics	Examples
P1	Ecosystem integration	Framework/tool integration and configuration	Nuxt i18n, Sitemap automation
P2	Module integration	Third‑party module integration, data flow and API design	Drizzle ORM, GitHub OAuth
P3	Logic refactoring	Core business logic design and refactoring	URL state binding, nested comments, theme design system
P4	Delivery automation	CI/CD, deployment, monitoring – delivery pipeline engineering	GitHub Actions + Docker/Caddy deployment
P5	Low‑level / core	Compiler extensions, plugin systems – infrastructure layer	(To be unlocked)

The classification is based on technical depth, not code volume. Readers can choose articles based on their skill level.

🌐 Part 5: Brand Ecosystem – From Theme to Community

General principle: A complete brand system includes: documentation (README, CHANGELOG, design documents), community interaction (open source, feedback channels), and ecosystem integration (deep integration with related tools to provide a consistent experience).

Moongate implementation:

5.1 Documentation System

README: Bilingual (Chinese/English) with preview images, design philosophy, optimization checklist, and recommended settings.
CHANGELOG: Version‑by‑version changes, folding older entries, highlighting current improvements.
Visual Contract: A standalone document attached to the theme.
Design System Document: Automatically generated DESIGN_SYSTEM.md with full color swatches, elevation system details, WCAG contrast data, and the Variable Selection Protocol.

5.2 Community Interaction

Open Source on GitHub: Public source code, accepting PRs.
Feedback Channels: Encouraging users to share calibration experiences to continuously improve the Visual Contract.
Ecosystem Integration:
- Better Comments Preset: Provides an official color preset so comment markers align with the theme’s semantic colors.
- Terminal ANSI Color Sync: Maps the 16‑color ANSI palette to the theme’s semantic colors, eliminating visual disconnect.
- Unified Design Assets: Through moongate-colors.css and moongate-layout.css, directly usable in blogs, documentation sites, and UI component libraries.

5.3 From Artifact to Brand

Moongate is no longer just a theme. It is:

A design philosophy (cool‑based foundation, semantic layering, Gravity Compensation, elevation system)
An engineering protocol (P1–P5 classification)
A visual contract (display calibration guide)
An extensible brand (light/dark, high‑contrast, and more variants in the future)

📌 Part 6: Summary and Outlook

With this, most of our five‑part series is complete. Looking back:

Part 1 (Basics): You created and published your first VS Code theme, mastering the core workflow.
Part 2 (Engineering): You refactored the theme to be maintainable and extensible.
Part 3 (Multi‑theme): You built multiple theme variants and introduced Gravity Compensation for visual consistency.
Part 4 (Design System): You elevated the theme to a design system with DTCG tokens, an elevation system, a Visual Contract, a Protocol Index, and automated asset generation. v2.2.0 is the living proof of this system – every color is industrially verified, layout tokens are exported as CSS variables, and design documentation is generated automatically.
Part 5 (Deep Dive): If you want to go deeper into the full implementation of the industrial‑grade build script – including color normalization, contrast checking, circular reference detection, and automated asset generation – Part 5: Industrial‑Grade Build Scripts & DTCG Implementation (coming soon).

Moongate Theme is the practical result of this series. If you want to experience the design philosophy firsthand, search for Moongate Theme in the VS Code Marketplace, or explore via the links below:

If you create your own theme using this series, or have any questions or ideas, feel free to share them in the comments. The code world is vast – there will always be someone who loves the same moonlight as you.

Explore endlessly, code without limits.

⬆ Back to top

This article is part of the **VS Code Theme Development Guide* series. The original Chinese version is available on my blog: moongate.top.*

Light, Dark, and Beyond: Building Multi‑theme Variants with Gravity Compensation

yuelinghuashu — Sat, 28 Mar 2026 14:48:30 +0000

🌗 Introduction: Why Do We Need Multiple Themes?

A good theme shouldn’t have just one face. Users work in different lighting conditions and at different times of day, and they may have personal preferences for a particular visual style. Providing both dark and light themes – and even more variants like high‑contrast – not only covers a wider audience but is also a crucial step toward turning your theme into a true design system.

In Part 2 we already turned the theme source into an engineering project – managing colors with YAML and generating the final JSON with a build script. Now, on top of that, we’ll effortlessly build a family of themes that are visually consistent and weight‑balanced across variants.

🧱 1. Core Idea: Reuse Rules, Separate Colors

The key idea behind multi‑theme support is: all themes share the same syntax rules and UI color definitions; the only thing that changes is the actual values of the color variables.

Thus we need to completely separate color variables from the rule files. Each theme gets its own independent color variable file, while all rule files (like languages/*.yaml, workbench.yaml) only reference variable names.

About semantic rules: VS Code themes support two highlighting mechanisms: tokenColors (based on TextMate grammar scopes) and semanticTokenColors (based on semantic information from language servers). Semantic rules allow more precise coloring of code roles (variables, parameters, properties) and support modifiers like italics or underlines. In a multi‑theme setup, semantic.yaml also only references color variables, so semantic highlighting stays consistent across light and dark variants.

1.1 Evolving the Directory Structure

your-theme/
├── src/
│   ├── core/
│   │   ├── colors-dark.yaml       # Dark theme variables
│   │   ├── colors-light.yaml       # Light theme variables
│   │   ├── colors-hc-black.yaml    # High‑contrast dark theme
│   │   └── colors-hc-light.yaml    # High‑contrast light theme (optional)
│   ├── languages/                  # Language rules (completely reused)
│   ├── workbench.yaml              # UI colors (references variables)
│   └── semantic.yaml               # Semantic rules (references variables)
├── scripts/
│   └── build.js                    # Multi‑theme build script
└── themes/
    ├── your-theme-dark.json
    ├── your-theme-light.json
    ├── your-theme-hc-black.json
    └── your-theme-hc-light.json

1.2 Variable File Examples

colors-dark.yaml

# Dark theme
primary: "#3b82f6"
success: "#34d399"
warning: "#fbbf24"
error: "#f87171"
bg: "#0f172a"
text: "#e2e8f0"
# ... other variables

colors-light.yaml

# Light theme (variable names identical to dark version, only values differ)
primary: "#0284c7"
success: "#059669"
warning: "#b45309"
error: "#b91c1c"
bg: "#f9fafb"
text: "#1e293b"
# ... other variables

Key principle: All color files must use exactly the same variable names. This is the foundation for rule reuse.

1.3 Best Practices for Variable Naming

To make the theme system easy to maintain and extend, follow these semantic + compositional naming guidelines:

Semantic names: Use names that describe the purpose of the color (like primary, success) rather than a concrete color name (like blue). That way, even if the theme’s hue changes, the variable names stay the same.
Composition: For hierarchical relationships (backgrounds, text), use names like bgBase, bgElevated, textPrimary, textSecondary to instantly communicate the layering.

# Recommended naming
bgBase: "#0f172a"      # bottom layer background
bgElevated: "#131c31"   # raised surface background
bgMuted: "#1e293b"      # secondary background
textPrimary: "#e2e8f0" # primary text
textMuted: "#94a3b8"    # auxiliary text

When you add a new theme, you only need to assign appropriate values to these variables in the new color file – no changes to any rule files are required.

⚠️ Opacity Handling Best Practice

In the Moongate engineering system, color variables themselves should not include opacity. Opacity should be added via a suffix, for example ${primary}20 means 12.5% opacity of the primary color. The build script automatically appends the two‑digit hexadecimal suffix to a 6‑digit hex value (e.g., #3b82f6 + 20 = #3b82f620). If the variable already contains an 8‑digit hex (already has opacity), the script warns and ignores the suffix. This keeps opacity handling predictable and avoids accidental invalid colors.

⚖️ 2. Gravity Compensation: Making Light and Dark Visually Balanced

A light theme is not simply the inverse of a dark theme. On a dark background, light colors act like “light sources”; on a light background, dark colors act like “absorbers”. To achieve equal visual weight, we need Gravity Compensation – the same semantic role should use the same hue, but different lightness (and optionally saturation) across backgrounds.

Compensation Example Table

Semantic Role	Dark Theme	Light Theme	Explanation
primary	`#3b82f6` (60% lightness)	`#0284c7` (48% lightness)	Same blue hue, lower lightness for white background
success	`#34d399` (65%)	`#059669` (40%)	More restrained green, still high contrast
warning	`#fbbf24` (75%)	`#b45309` (35%)	From bright yellow to orange‑yellow, avoids “disappearing” on white
error	`#f87171` (60%)	`#b91c1c` (35%)	Deep red maintains its warning character

How to Determine Compensation Values in an Engineering Way?

Manually adjusting lightness by “feeling” is inefficient and inconsistent. Use the HSL color model for a scientific approach:

Convert the HEX value to HSL (Hue, Saturation, Lightness).
Keep Hue (H) unchanged – that’s the core of semantic consistency.
Lower Lightness (L) and optionally Saturation (S) for light backgrounds. A typical reduction is 20–30% in lightness, and sometimes 10–20% in saturation. You can use tools like chroma.js to programmatically generate the compensated values.

Example with chroma.js to create a light version of the primary color:

const darkPrimary = chroma("#3b82f6");
const lightPrimary = darkPrimary.set("hsl.l", 0.48); // set lightness to 48%

Saturation adjustment: In addition to lightness, saturation may also need fine‑tuning. On a dark background, high saturation can produce a pleasant “glow”, but the same saturation on a light background may feel harsh. Reducing saturation by 10–20% often yields a more comfortable look. With chroma.js you can adjust both:

const darkPrimary = chroma("#3b82f6");
const lightPrimary = darkPrimary.set("hsl.l", 0.48).set("hsl.s", 0.7); // lightness 48%, saturation 70%

With this mapping, users switching themes will perceive the same visual weight for each semantic role – no re‑learning needed.

🔨 3. Build Script Upgrade: Automatically Generate Multiple Themes

Building on the script from Part 2, we need only a few enhancements to support multiple themes. The following code snippets highlight the core additions (the full script is in the appendix).

3.1 Scanning Color Files

📁 Custom paths: If your project structure differs (for example, you keep language rules in src/tokens/languages), adjust the PATHS object accordingly. The script uses the recommended structure, but you can freely modify the paths.

const colorFiles = fs
  .readdirSync(coreDir)
  .filter((f) => f.startsWith("colors-") && f.endsWith(".yaml"));

colorFiles.forEach((file) => {
  const match = file.match(/^colors-(.+)\.yaml$/);
  if (!match) return;
  const themeType = match[1]; // 'dark', 'light', 'hc-black', 'hc-light', etc.
  // ... load color variables and build theme
});

3.2 Theme Type Mapping (Display Name & uiTheme)

Define a map to produce friendly display names and the correct uiTheme for each variant:

const themeDisplayMap = {
  dark: { suffix: "Dark", uiTheme: "vs-dark" },
  light: { suffix: "Light", uiTheme: "vs" },
  "hc-black": { suffix: "High Contrast (Black)", uiTheme: "hc-black" },
  "hc-light": { suffix: "High Contrast (Light)", uiTheme: "hc-light" },
  // add more as needed
};

// During theme generation:
const display = themeDisplayMap[themeType] || {
  suffix: themeType,
  uiTheme: "vs-dark",
};
const themeName = `${themeInfo.displayName} ${display.suffix}`;
const uiTheme = display.uiTheme;
// Determine the theme.type field ('dark' or 'light') from the themeType
const type = themeType.includes("light") ? "light" : "dark";

3.3 Enhanced Variable Replacement (with Opacity Safety Net)

function replaceVariables(obj, colors) {
  if (typeof obj === "string") {
    return obj.replace(
      /\$\{([a-zA-Z0-9_-]+)\}([0-9a-fA-F]{2})?/g,
      (match, key, alpha) => {
        const value = colors[key];
        if (!value) {
          console.warn(`⚠️ Variable "${key}" not defined`);
          return match;
        }
        // Intelligent opacity handling
        if (alpha && /^#[0-9a-fA-F]{6}$/.test(value)) {
          return value + alpha; // 6‑digit hex + suffix
        }
        if (alpha && /^#[0-9a-fA-F]{8}$/.test(value)) {
          console.warn(`⚠️ Variable "${key}" already contains opacity, ignoring suffix`);
          return value;
        }
        return value;
      },
    );
  }
  // ... handle arrays and objects
}

3.4 Reading Theme Info from package.json

const pkg = require("../package.json");
const baseName = pkg.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();

3.5 Debugging Multiple Themes

While developing, you may want to build only a specific theme to speed up iteration. You can add command‑line argument support to the script, but the default workflow works well:

Run npm run build to generate all theme JSON files.
Press F5 to start the Extension Development Host.
In the development host, open the command palette (Ctrl+Shift+P) and select “Preferences: Color Theme”. You’ll see all registered themes (dark, light, high‑contrast). Quickly switch to verify the look.
After editing color variable files, simply re‑run npm run build and then “Developer: Reload Window” in the development host to see the updates.

📦 4. Registering Multiple Themes

In package.json, add an entry for each theme in contributes.themes. Pay attention to the uiTheme field:

"contributes": {
  "themes": [
    {
      "label": "Moongate Dark",
      "uiTheme": "vs-dark",
      "path": "./themes/moongate-dark.json"
    },
    {
      "label": "Moongate Light",
      "uiTheme": "vs",
      "path": "./themes/moongate-light.json"
    },
    {
      "label": "Moongate High Contrast (Black)",
      "uiTheme": "hc-black",
      "path": "./themes/moongate-hc-black.json"
    },
    {
      "label": "Moongate High Contrast (Light)",
      "uiTheme": "hc-light",
      "path": "./themes/moongate-hc-light.json"
    }
  ]
}

uiTheme values determine the theme type:
- Dark standard themes: "vs-dark"
- Light standard themes: "vs"
- High‑contrast dark themes: "hc-black"
- High‑contrast light themes: "hc-light"
The label appears in the VS Code command palette’s theme list; it’s a good practice to match the generated theme name or make it user‑friendly.

🌈 5. Adding Even More Theme Variants

With the same foundation, you can easily add new variants:

Create a new color file – e.g., colors-hc-black.yaml (high‑contrast dark), colors-hc-light.yaml (high‑contrast light), or colors-sepia.yaml (a retro style).
Use the same variable names as the base themes, but assign different values.
The build script will automatically scan the new file and generate the corresponding JSON.
Register the new theme in package.json, setting the correct uiTheme for its type.

No modifications to any language rules or UI definitions are required. Maintenance cost stays near zero.

Example: High‑Contrast Dark Theme

# colors-hc-black.yaml
primary: "#ffff00" # bright yellow
success: "#00ff00" # bright green
warning: "#ff8800"
error: "#ff0000"
bg: "#000000"
text: "#ffffff"
# ... other variables use extremely high‑contrast values

🧠 6. Maintenance Advice

Semantic naming: Use names like primary, success, bg, text. Avoid concrete color names like blue. This keeps rule files independent of the actual color values.
Keep rule files theme‑agnostic: No hard‑coded color values should appear in any rule file (languages/, workbench.yaml, semantic.yaml). Only variables.
Use the build script’s safety net: Ensure the variable replacement function handles opacity suffixes, already‑opaque variables, and missing variables gracefully.
Version control: Commit the color variable files, but ignore the generated JSON files (unless you want to preview the result). Add themes/*.json to .gitignore, but keep !themes/.gitkeep to preserve the directory.
Pre‑publish check: Run the build script and manually verify that the generated JSON files are correct and colors are properly replaced.

⚠️ 7. Common Issues & Traps

Problem	Possible Cause	Solution
Theme doesn’t appear in color theme list	Not registered correctly in `package.json` or wrong JSON path	Check `contributes.themes` entries and ensure `path` points to the correct file.
Light theme looks like dark	`uiTheme` mistakenly set to `"vs-dark"`	For light themes, use `"vs"`.
High‑contrast theme looks wrong	`uiTheme` not using `"hc-black"` or `"hc-light"`	Set the appropriate `uiTheme` based on the theme type.
Color variable not replaced, shows `${var}`	Misspelled variable name, or variable not defined	Check spelling and ensure the variable is defined in the color file.
Opacity effects are off (too dark/light)	Variable already contains opacity and suffix added	Never pre‑include opacity in variables; always use suffix like `${var}20`.
Build script says “file not found”	Missing required YAML file	Ensure `src/core/`, `src/languages/`, etc., exist and contain needed files.
New color file not picked up	Filename doesn’t match `colors-*.yaml` pattern	Rename to start with `colors-` and end with `.yaml`.

🚀 8. From Multiple Themes to a Design System

Building multiple themes means your theme has evolved from a single color scheme into an extensible visual system. Next, you can:

Define a design philosophy – such as cool‑based foundations, semantic layering, and gravity compensation – to give every color a rationale.
Offer a visual contract – provide a display calibration guide to help users see your theme as intended on different hardware.
Create a protocol index – categorize your blog articles by difficulty, linking them to your theme to form a brand ecosystem.

All these will be explored in depth in Part 4.

📌 9. Summary

By separating color variables and enhancing the build script, we’ve smoothly extended from a single theme to multiple variants. Key takeaways:

Rule reuse: All themes share the same language and UI definitions, making maintenance almost zero.
One‑click generation: The build script automatically scans color files and produces multiple theme JSON files.
Unlimited extension: Adding a new theme only requires a new color file; no other code changes.
Gravity Compensation: Light and dark variants have equal visual weight, so switching themes feels seamless.
Proper registration: With the mapping table and correct uiTheme settings, each theme appears correctly in VS Code.

Now your theme can generate dark, light, and even high‑contrast variants in one go, with Gravity Compensation ensuring they feel balanced. Users can switch based on their environment, and you still have zero maintenance overhead.

But a truly outstanding theme is more than a set of colors. It deserves its own design philosophy, a contract with the user, and even to become the core asset of your technical brand. In Part 4 we’ll take the final leap – from engineering to a design system, building a complete theme brand ecosystem with the Visual Contract, Protocol Index, and other original concepts.

Part 4: From Theme to Design System: Visual Contracts and Brand Ecosystems

Explore endlessly, code without limits.

⬆ Back to top

📎 Appendix: Full Build Script Reference

📁 Custom paths: If your project structure differs, adjust the PATHS object accordingly. The script uses the recommended structure, but you can freely modify it.

Click to expand the full build script

// scripts/build.js
// Full script code with all enhancements described above

const fs = require("fs");
const yaml = require("js-yaml");
const path = require("path");

const ROOT_DIR = path.resolve(__dirname, "..");

// ==================== Path Configuration ====================
const PATHS = {
  workbench: path.join(ROOT_DIR, "src", "workbench.yaml"),
  semantic: path.join(ROOT_DIR, "src", "semantic.yaml"),
  langDir: path.join(ROOT_DIR, "src", "languages"),
  specialDir: path.join(ROOT_DIR, "src", "special"),
  coreDir: path.join(ROOT_DIR, "src", "core"),
  outputDir: path.join(ROOT_DIR, "themes"),
};

// ==================== Helper Functions ====================

function ensureFileExists(filePath, description) {
  if (!fs.existsSync(filePath)) {
    throw new Error(`❌ ${description} file not found: ${filePath}`);
  }
}

function safeLoadYaml(filePath, description) {
  try {
    return yaml.load(fs.readFileSync(filePath, "utf8"));
  } catch (err) {
    console.error(`❌ Failed to parse ${description} (${filePath}):`, err.message);
    return null;
  }
}

function replaceVariables(obj, colors) {
  if (typeof obj === "string") {
    return obj.replace(
      /\$\{([a-zA-Z0-9_-]+)\}([0-9a-fA-F]{2})?/g,
      (match, key, alpha) => {
        const value = colors[key];
        if (value === undefined) {
          console.warn(`⚠️ Warning: variable "${key}" not defined, keeping placeholder`);
          return match;
        }

        if (alpha) {
          if (/^#[0-9a-fA-F]{8}$/.test(value)) {
            console.warn(
              `⚠️ Warning: variable "${key}" value ${value} already contains opacity, ignoring suffix "${alpha}"`,
            );
            return value;
          }
          if (/^#[0-9a-fA-F]{6}$/.test(value)) {
            return value + alpha;
          }
          console.warn(
            `⚠️ Warning: variable "${key}" value ${value} has unsupported format, cannot apply opacity`,
          );
          return value;
        }
        return value;
      },
    );
  }
  if (Array.isArray(obj)) {
    return obj.map((item) => replaceVariables(item, colors));
  }
  if (obj && typeof obj === "object") {
    const result = {};
    for (const [k, v] of Object.entries(obj)) {
      result[k] = replaceVariables(v, colors);
    }
    return result;
  }
  return obj;
}

function getThemeInfo() {
  const pkgPath = path.join(ROOT_DIR, "package.json");
  if (!fs.existsSync(pkgPath)) {
    return { name: "your-theme", displayName: "Your Theme" };
  }
  try {
    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
    let displayName = pkg.displayName || pkg.name || "Your Theme";
    if (displayName.startsWith("@") && displayName.includes("/")) {
      displayName = displayName.split("/")[1];
    }
    return {
      name: pkg.name || "your-theme",
      displayName,
    };
  } catch {
    return { name: "your-theme", displayName: "Your Theme" };
  }
}

// Theme display name and uiTheme mapping
const themeDisplayMap = {
  dark: { suffix: "Dark", uiTheme: "vs-dark" },
  light: { suffix: "Light", uiTheme: "vs" },
  "hc-black": { suffix: "High Contrast (Black)", uiTheme: "hc-black" },
  "hc-light": { suffix: "High Contrast (Light)", uiTheme: "hc-light" },
  // extend as needed
};

// ==================== Main ====================
function main() {
  console.log("🚀 Building theme (multi‑theme + Gravity Compensation)...\n");

  // 1. Check required files
  try {
    ensureFileExists(PATHS.workbench, "workbench");
    ensureFileExists(PATHS.semantic, "semantic");
    ensureFileExists(PATHS.coreDir, "core directory");
  } catch (err) {
    console.error(err.message);
    process.exit(1);
  }

  // 2. Load shared rules
  console.log("📦 Loading shared rules...");
  const workbenchRaw = safeLoadYaml(PATHS.workbench, "workbench.yaml");
  const semanticRaw = safeLoadYaml(PATHS.semantic, "semantic.yaml");
  if (!workbenchRaw || !semanticRaw) process.exit(1);

  // 3. Collect language rules
  console.log("📚 Loading language rules...");
  let tokenColorsRaw = [];
  if (fs.existsSync(PATHS.langDir)) {
    const langFiles = fs
      .readdirSync(PATHS.langDir)
      .filter((f) => f.endsWith(".yaml"))
      .sort();
    langFiles.forEach((file) => {
      const filePath = path.join(PATHS.langDir, file);
      const langRules = safeLoadYaml(filePath, `language rules ${file}`);
      if (langRules?.tokenColors) {
        tokenColorsRaw = tokenColorsRaw.concat(langRules.tokenColors);
        console.log(`   ✅ Loaded: ${file}`);
      }
    });
  } else {
    console.warn("⚠️ languages directory not found, skipping language rules");
  }

  // 4. Load special rules
  console.log("✨ Loading special rules...");
  if (fs.existsSync(PATHS.specialDir)) {
    const specialFiles = fs
      .readdirSync(PATHS.specialDir)
      .filter((f) => f.endsWith(".yaml"));
    specialFiles.forEach((file) => {
      const filePath = path.join(PATHS.specialDir, file);
      const specialRules = safeLoadYaml(filePath, `special rules ${file}`);
      if (specialRules?.tokenColors) {
        tokenColorsRaw = tokenColorsRaw.concat(specialRules.tokenColors);
        console.log(`   ✅ Loaded: ${file}`);
      }
    });
  } else {
    console.log("ℹ️ special directory not found, skipping special rules");
  }

  // 5. Find color variable files
  console.log("\n🎨 Scanning color variable files...");
  const colorFiles = fs
    .readdirSync(PATHS.coreDir)
    .filter((f) => f.startsWith("colors-") && f.endsWith(".yaml"));

  if (colorFiles.length === 0) {
    console.error("❌ No colors-*.yaml files found in core directory");
    process.exit(1);
  }

  // 6. Read theme info
  const themeInfo = getThemeInfo();
  let baseName = themeInfo.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();

  // 7. Build each theme
  console.log(`\n🔨 Building themes (base name: ${baseName})...\n`);
  colorFiles.forEach((colorFile) => {
    const match = colorFile.match(/^colors-(.+)\.yaml$/);
    if (!match) return;
    const themeType = match[1]; // e.g., 'dark', 'light', 'hc-black'
    const outputFile = path.join(PATHS.outputDir, `${baseName}-${themeType}.json`);

    // Load color variables
    const colorsPath = path.join(PATHS.coreDir, colorFile);
    const colors = safeLoadYaml(colorsPath, `color variables ${colorFile}`);
    if (!colors) {
      console.error(`   ❌ Skipping ${colorFile}`);
      return;
    }

    // Replace variables
    const uiColors = replaceVariables(workbenchRaw, colors);
    const semanticColors = replaceVariables(semanticRaw, colors);
    const tokenColors = replaceVariables(tokenColorsRaw, colors);

    // Determine display name and uiTheme
    const display = themeDisplayMap[themeType] || {
      suffix: themeType,
      uiTheme: "vs-dark",
    };
    const themeName = `${themeInfo.displayName} ${display.suffix}`;

    // Map theme.type field
    const themeTypeMap = {
      dark: "dark",
      light: "light",
      "hc-black": "dark",
      "hc-light": "light",
    };
    const type = themeTypeMap[themeType] || "dark";

    const theme = {
      name: themeName,
      type: type,
      colors: uiColors,
      tokenColors: tokenColors,
      semanticTokenColors: semanticColors,
    };

    // Ensure output directory exists
    if (!fs.existsSync(PATHS.outputDir)) {
      fs.mkdirSync(PATHS.outputDir, { recursive: true });
    }

    fs.writeFileSync(outputFile, JSON.stringify(theme, null, 2));
    console.log(`   ✅ Built: ${outputFile}`);
  });

  console.log("\n🎉 All themes built successfully!");
}

main();

This article is part of the **VS Code Theme Development Guide* 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*

Stop Hand-Editing JSON: Engineering Your VS Code Theme with YAML

yuelinghuashu — Sat, 21 Mar 2026 00:56:32 +0000

In Part 1, you learned how to create and publish your first VS Code theme from scratch. But as your theme grows, you probably run into these problems:

A single JSON file becomes thousands of lines long; changing one color means hunting across the file and risking mistakes.
Adding syntax highlighting for different languages means piling rules into one huge tokenColors array—hard to read, even harder to maintain.
Wanting a light version? You have to duplicate the whole file and manually tweak hundreds of color values.

It’s time to bring engineering to your theme. This guide will show you how to refactor your monolithic JSON theme into a modular, maintainable project using YAML and a build script. You’ll end up with a clean, extensible source structure that makes future updates a breeze.

📦 Prerequisites

Make sure you have Node.js and npm (or pnpm) installed. Then install the build dependency:

npm install --save-dev js-yaml

⚠️ Note: js-yaml must be installed as a dev dependency—it’s only used during development, not shipped with the final theme.

📁 Directory Structure

We’ll put source files under src/, the build script in scripts/, and the generated JSON in themes/. A recommended layout:

your-theme/
├── src/
│   ├── core/
│   │   └── colors.yaml          # color variables (primary, background, etc.)
│   ├── languages/                # syntax rules per language
│   │   ├── base.yaml             # common rules for all languages
│   │   ├── javascript.yaml
│   │   ├── typescript.yaml
│   │   ├── python.yaml
│   │   ├── html.yaml
│   │   ├── css.yaml
│   │   └── ... (more languages)
│   ├── special/                   # special rules (e.g., Better Comments)
│   │   └── better-comments.yaml
│   ├── workbench.yaml             # UI colors (the `colors` object)
│   └── semantic.yaml              # semantic highlighting rules
├── scripts/
│   └── build.js                   # build script
├── themes/
│   └── your-theme.json            # final generated JSON (rename to match your theme)
├── package.json
└── .vscodeignore

🎨 Step 1: Extract Color Variables

Open your original theme JSON. Identify all color values that appear in the colors object and repeated colors in tokenColors. Turn them into variables. Create src/core/colors.yaml:

# Core color variables
primary: "#3b82f6"   # main blue
success: "#34d399"   # success green
warning: "#fbbf24"   # warning yellow
error: "#f87171"     # error red
highlight: "#7dd3fc" # glowing blue

bg: "#0f172a"        # background
bgMuted: "#1e293b"   # secondary background
text: "#e2e8f0"      # foreground
textMuted: "#94a3b8" # muted text
border: "#2d3748"    # borders

# ... more variables

Important rules:

Use camelCase or lowercase with underscores (e.g., primary, bg_muted). The regex in the build script expects variable names consisting of letters, numbers, and underscores.
Do NOT include opacity in variable definitions. Instead, apply opacity when referencing the variable, like ${primary}20. The build script will handle that.
Make sure every variable used elsewhere is defined here, otherwise the build will warn and leave ${var} unchanged, causing invalid colors.

✂️ Step 2: Split Syntax Rules

Break the tokenColors array into separate YAML files per language. Start with src/languages/base.yaml for rules common to all languages:

# Common rules
tokenColors:
  - name: Comment
    scope: ["comment", "punctuation.definition.comment"]
    settings:
      fontStyle: "italic"
      foreground: "${comment}"

  - name: Keyword
    scope: ["keyword", "storage.type", "storage.modifier"]
    settings:
      foreground: "${primary}"
      fontStyle: "bold"

  - name: String
    scope: ["string", "string.quoted.single", "string.quoted.double"]
    settings:
      foreground: "${success}"
  # ... more common rules

For language-specific rules, e.g., src/languages/javascript.yaml:

# JavaScript specific rules
tokenColors:
  - name: JSX Tag
    scope: ["entity.name.tag.jsx", "meta.tag.jsx"]
    settings:
      foreground: "${function}"

Do the same for other languages. If a language has no special rules yet, you can still create an empty array to keep the file present (or skip it – the script only includes files listed in the merge order).

🧩 Step 3: Split UI Colors and Semantic Rules

Move the entire colors object to src/workbench.yaml and replace color values with variable references:

# Editor UI colors
editor.background: "${bg}"
editor.foreground: "${text}"
titleBar.activeBackground: "${bg}"
titleBar.activeForeground: "${text}"
statusBar.background: "${bg}"
statusBar.foreground: "${textMuted}"
# ... all UI keys

Move semanticTokenColors to src/semantic.yaml:

# Semantic highlighting rules
variable: "${variable}"
function: "${function}"
class: "${warning}"
"*.decorator":
  foreground: "${purple}"
  fontStyle: "italic"
# ... other semantic rules

🔍 Note: In YAML, keys with special characters (like *.decorator) must be quoted.

🔨 Step 4: Write the Build Script

Create scripts/build.js. This script will:

Load colors.yaml to get the variable dictionary.
Load workbench.yaml, semantic.yaml, and all language rules.
Recursively replace ${variable} with actual color values (and handle opacity suffixes).
Merge tokenColors in a specified order.
Output the final JSON to themes/.

Here’s a complete example (replace your-theme with your actual theme name):

const fs = require("fs");
const yaml = require("js-yaml");
const path = require("path");

const ROOT_DIR = path.resolve(__dirname, "..");

// Paths
const COLOR_FILE = path.join(ROOT_DIR, "src", "core", "colors.yaml");
const WORKBENCH_FILE = path.join(ROOT_DIR, "src", "workbench.yaml");
const SEMANTIC_FILE = path.join(ROOT_DIR, "src", "semantic.yaml");
const LANG_DIR = path.join(ROOT_DIR, "src", "languages");
const SPECIAL_DIR = path.join(ROOT_DIR, "src", "special");
const OUTPUT_FILE = path.join(ROOT_DIR, "themes", "your-theme.json"); // rename

// Load color variables
const colors = yaml.load(fs.readFileSync(COLOR_FILE, "utf8"));

// Recursive variable replacement (supports opacity suffix)
function replaceVariables(obj) {
  if (typeof obj === "string") {
    return obj.replace(/\$\{([a-zA-Z0-9_-]+)\}([0-9a-fA-F]{2})?/g, (match, key, alpha) => {
      if (colors[key] !== undefined) {
        return colors[key] + (alpha || "");
      }
      console.warn(`Warning: variable "${key}" not defined, keeping placeholder`);
      return match;
    });
  }
  if (Array.isArray(obj)) {
    return obj.map(replaceVariables);
  }
  if (obj && typeof obj === "object") {
    const result = {};
    for (const [k, v] of Object.entries(obj)) {
      result[k] = replaceVariables(v);
    }
    return result;
  }
  return obj;
}

// Load and replace UI colors
const workbench = yaml.load(fs.readFileSync(WORKBENCH_FILE, "utf8"));
const uiColors = replaceVariables(workbench);

// Load and replace semantic rules
const semantic = yaml.load(fs.readFileSync(SEMANTIC_FILE, "utf8"));
const semanticColors = replaceVariables(semantic);

// Language rule merge order (later files override earlier ones)
const order = [
  "base.yaml",
  "html.yaml",
  "css.yaml",
  "javascript.yaml",
  "typescript.yaml",
  "vue.yaml",
  "json.yaml",
  "markdown.yaml",
  "python.yaml",
  "jsdoc.yaml",
  // add more as needed
];

let tokenColors = [];

order.forEach((file) => {
  const filePath = path.join(LANG_DIR, file);
  if (fs.existsSync(filePath)) {
    try {
      const langRules = yaml.load(fs.readFileSync(filePath, "utf8"));
      if (langRules?.tokenColors) {
        tokenColors = tokenColors.concat(langRules.tokenColors);
      }
    } catch (err) {
      console.error(`Failed to parse ${file}:`, err.message);
    }
  } else {
    console.warn(`File ${file} not found, skipping`);
  }
});

// Load special rules (e.g., Better Comments)
const specialFile = path.join(SPECIAL_DIR, "better-comments.yaml");
if (fs.existsSync(specialFile)) {
  const specialRules = yaml.load(fs.readFileSync(specialFile, "utf8"));
  if (specialRules?.tokenColors) {
    tokenColors = tokenColors.concat(specialRules.tokenColors);
    console.log("✅ Loaded Better Comments rules");
  }
}

const processedTokenColors = replaceVariables(tokenColors);

// Ensure output directory exists
const outputDir = path.dirname(OUTPUT_FILE);
if (!fs.existsSync(outputDir)) {
  fs.mkdirSync(outputDir, { recursive: true });
}

// Build final theme object
const newTheme = {
  name: "Your Theme Name", // change to your theme's display name
  type: "dark", // or "light"
  colors: uiColors,
  tokenColors: processedTokenColors,
  semanticTokenColors: semanticColors,
};

// Write JSON
fs.writeFileSync(OUTPUT_FILE, JSON.stringify(newTheme, null, 2));
console.log("✅ Theme built successfully!");

Important notes:

The order array controls the merge priority: rules from later files override earlier ones for the same scope. Put general rules first, then language-specific ones.
If a variable is missing, the script will warn and leave ${var} unchanged. Make sure all variables are defined.
Opacity suffixes are only supported as two hex digits (20). Do not pre‑include opacity in your variable definitions.

⚙️ Step 5: Add Scripts to package.json

Add build commands to your package.json:

{
  "scripts": {
    "build": "node scripts/build.js",
    "prepublishOnly": "npm run build"
  }
}

Double-check that js-yaml is in devDependencies, not dependencies.

✨ Step 6: Add Watch Mode for Development

Running npm run build every time you change a YAML file gets tedious. Add a watch mode to auto‑rebuild.

1. Install nodemon

npm install --save-dev nodemon

2. Add watch scripts to package.json

{
  "scripts": {
    "build": "node scripts/build.js",
    "watch": "nodemon --watch src -e yaml --exec \"npm run build\"",
    "dev": "npm run watch",
    "prepublishOnly": "npm run build"
  }
}

Now run npm run watch in your terminal. Whenever you save a YAML file inside src/, the build script will run automatically. In the Extension Development Host window (F5), you can then reload (Ctrl+R) to see changes instantly.

📦 Step 7: Update .vscodeignore

Make sure your .vscodeignore excludes source files and dependencies, but keeps the generated JSON. A minimal example:

.vscode/**
.gitignore
vsc-extension-quickstart.md
node_modules
pnpm-lock.yaml
src/**
scripts/**
!themes/*.json

💡 !themes/*.json tells the packager to include all JSON files in the themes folder.

✅ Step 8: Test the Build

Run the build:

npm run build

Check the generated themes/your-theme.json against your original JSON (if you still have it). Use a diff tool to spot any unintended differences. Common issues:

Missing variables → ensure all used variables are defined in colors.yaml.
Opacity not working → check that opacity is applied as a two‑digit suffix (${primary}20) and that the base color is a 6‑digit hex.
Wrong rule order → adjust the order array in build.js.

🚀 Step 9: Enjoy Engineering Your Theme

Now your theme source is modular and easy to maintain:

Want to change the primary color? Edit one line in colors.yaml.
Need a new rule for Python? Just add it to python.yaml.
Thinking about a light version? Later we’ll see how to add multiple color schemes with almost zero extra work.

🔍 Troubleshooting

Problem	Possible Cause	Solution
Colors appear as `${var}` in the JSON	Variable not defined in `colors.yaml`	Check spelling; add the missing variable
Opacity not applied correctly	Variable already includes alpha or opacity suffix wrong	Remove alpha from variable; use `${var}20`
Some language rules missing	Language file not listed in `order`	Add file name to the `order` array
Rules overridden unintentionally	Merge order wrong	Place more specific rules later in `order`
`vsce package` fails because of missing dependencies	`js-yaml` in `dependencies`	Move it to `devDependencies`
Variable names with hyphens or special characters not replaced	Variable name contains characters not supported by the variable replacement regex (e.g., hyphens `-`)	Use only letters, numbers, and underscores in variable names. If you need hyphens, ensure your build script uses a regex that supports them (e.g., `[a-zA-Z0-9_-]+`).

📝 Summary

By engineering your theme, you’ve moved from a fragile, monolithic JSON to a clean, scalable design system. This not only improves maintainability but also makes it easy to add more features and even create an entire family of themes.

But what if you want both a dark and a light version, and you want them to feel visually balanced? That’s exactly what Part 3 covers—building multi‑theme variants and introducing the concept of Gravity Compensation to ensure consistent visual weight across themes.

Part 3: Light, Dark, and Beyond: Building Multi‑theme Variants with Gravity Compensation

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

yuelinghuashu — Sat, 14 Mar 2026 03:42:04 +0000

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:

New Color Theme
No, start fresh (don't import an existing theme)
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)
Choose a base theme: Dark or Light
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:

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.
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

Open your project folder in VS Code.
Press F5 to launch the Extension Development Host window.
In the new window, press Ctrl+K Ctrl+T and select your theme.
Open a test code file to see the theme in action.
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:

Make sure you have successfully generated the .vsix file with vsce package.
Go to the VS Code Marketplace management page and log in with your Microsoft account.
Click on your publisher name, then the Publish extension button in the top right.
Select your .vsix file and upload.
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

DEV Community: yuelinghuashu

From Theme to Design System: Visual Contracts and Brand Ecosystems

🌕 Introduction: From Engineering to a Design System

🎨 Part 1: Design Philosophy – Giving Every Color a Meaning

1.1 Cool‑Based Foundation: Eliminating Visual “Dirt”

1.2 Semantic Layering: The Three Tiers of Information

1.3 Gravity Compensation: Visual Weight Parity Between Day and Night

1.4 Elevation System: Giving the UI Physical Depth

🔷 Part 2: DTCG Design Tokens – Turning Colors into Engineering Assets

Industrial‑Grade Quality Checks

📄 Part 3: Visual Contract – Connecting the User and the Hardware

🔷 Part 4: Protocol Index – Turning Content into Assets

🌐 Part 5: Brand Ecosystem – From Theme to Community

5.1 Documentation System

5.2 Community Interaction

5.3 From Artifact to Brand

📌 Part 6: Summary and Outlook

Light, Dark, and Beyond: Building Multi‑theme Variants with Gravity Compensation

🌗 Introduction: Why Do We Need Multiple Themes?

🧱 1. Core Idea: Reuse Rules, Separate Colors

1.1 Evolving the Directory Structure

1.2 Variable File Examples

1.3 Best Practices for Variable Naming

⚖️ 2. Gravity Compensation: Making Light and Dark Visually Balanced

Compensation Example Table

How to Determine Compensation Values in an Engineering Way?

🔨 3. Build Script Upgrade: Automatically Generate Multiple Themes

3.1 Scanning Color Files

3.2 Theme Type Mapping (Display Name & uiTheme)

3.3 Enhanced Variable Replacement (with Opacity Safety Net)

3.4 Reading Theme Info from package.json

3.5 Debugging Multiple Themes

📦 4. Registering Multiple Themes

🌈 5. Adding Even More Theme Variants

Example: High‑Contrast Dark Theme

🧠 6. Maintenance Advice

⚠️ 7. Common Issues & Traps

🚀 8. From Multiple Themes to a Design System

📌 9. Summary

📎 Appendix: Full Build Script Reference

Stop Hand-Editing JSON: Engineering Your VS Code Theme with YAML

📦 Prerequisites

📁 Directory Structure

🎨 Step 1: Extract Color Variables

✂️ Step 2: Split Syntax Rules

🧩 Step 3: Split UI Colors and Semantic Rules

🔨 Step 4: Write the Build Script

⚙️ Step 5: Add Scripts to package.json

✨ Step 6: Add Watch Mode for Development

1. Install nodemon

2. Add watch scripts to package.json

📦 Step 7: Update .vscodeignore

✅ Step 8: Test the Build

🚀 Step 9: Enjoy Engineering Your Theme

🔍 Troubleshooting

📝 Summary

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

1. Prerequisites

2. Generate the Theme Project

3. Core Concepts: colors and tokenColors

🔍 How to Find the Correct Color Keys

🎨 Configuration Example

4. Local Debugging

🔧 Debugging Tip: Master the Inspect Tool

5. Polish the Details

1. Status Bar, Title Bar, etc.

2. Contrast

3. Semantic Highlighting (Advanced)

6. Prepare for Publishing

1. Complete package.json

2. Prepare Screenshots

3. Write a README.md

4. Add a License

5. Create a .vscodeignore

Pre‑Publishing Checklist

7. Package and Publish

1. Install Publishing Tool

2. Test Packaging

3. Get a Personal Access Token

4. Log In and Publish

3. Core Concepts: `colors` and `tokenColors`

1. Complete `package.json`

5. Create a `.vscodeignore`