🌕 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.mdwith 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.cssandmoongate-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 – continue with Part 5: Industrial‑Grade Build Scripts & DTCG Implementation.
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.
This article is part of the **VS Code Theme Development Guide* series. The original Chinese version is available on my blog: moongate.top.*
© 2026 yuelinghuashu. This work is licensed under CC BY-NC 4.0.
Top comments (0)