vscode-amber/docs/ARCHITECTURE.md

🏗️ Technical Architecture: MUTHUR-6000 VS Code Theme

This document describes the compilation pipeline, component structure, and tokenization architecture of the MUTHUR-6000 theme suite. It explains how themes are dynamically compiled, the structural separation between UI and syntax tokens, and instructions for extending the TextMate scope mappings.

---

🏗️ 1. Programmatic Theme Compilation Pipeline

Maintaining four separate theme files, each containing hundreds of repetitive workbench and syntax color definitions, leads to high maintenance costs and layout inconsistencies. The MUTHUR-6000 project resolves this by using a programmatic Single Point of Truth (SPoT) compile process:

[ tokens.js ] ────────┐
                      ├─> [ compiler.js (Node.js Builder) ] ─> [ /themes/ compiled JSONs ]
[ theme-template.json ] ┘

Components of the Pipeline:

1. tokens.js: Holds the color definitions for each variant (Amber, Green, Blue, Red). If you modify a color hex in tokens.js, the change will immediately propagate to the compiled output.
2. theme-template.json: The universal blueprints file containing standard VS Code color keys (e.g. "editor.background", "editorCursor.foreground") and TextMate token scopes using string template variables (e.g. "${themeBg}", "${syntaxKeyword}").
3. compiler.js: A lightweight Node.js script that replaces the placeholders in the template with corresponding hex codes from the tokens, validates that the output compiles to valid JSON (RFC 8259), and writes it to the ./themes/ directory.

---

⌨️ 2. Repository Layout & File Mapping

The file structure is organized as follows:

vscode-amber/
├── .gitignore               # Configures files excluded from Git tracking
├── package.json             # Extension manifest, declares theme variants to VS Code
├── compiler.js              # Theme compiler script
├── tokens.js                # Core color tokens for the 4 variants
├── theme-template.json      # Base template mapping tokens to TextMate scopes
├── effects.css              # Custom stylesheet for external CRT simulation
├── icon.png                 # Extension marketplace icon
├── docs/                    # Compliance documentation folder
│   ├── DESIGN.md            # Visual specifications & CRT setup guide
│   ├── ARCHITECTURE.md      # Compiler framework & token structure
│   └── SECURITY.md          # Packaging, publishing, and audit protocols
└── themes/                  # Target output directory (Compiled JSON files)
    ├── muthur-6000-amber-color-theme.json
    ├── muthur-6000-green-color-theme.json
    ├── muthur-6000-blue-color-theme.json
    └── muthur-6000-red-color-theme.json

---

🎨 3. Mapping Tokens to TextMate Scopes

To implement the "Premium Analog-Hybrid" design:

• Workbench UI Frame: Colors such as bg, bgAlt, border, and borderActive map directly to sidebars, tab headers, title bars, and panel outlines. This locks the VS Code frame to a high-contrast terminal console.
• Editor Code Syntax: TextMate scopes are matched to dynamic syntax variables (syntaxKeyword, syntaxFunction, syntaxString, syntaxComment, etc.). For languages like TypeScript/JavaScript, Python, C++, Go, HTML, and Markdown, the scopes are mapped explicitly in theme-template.json.

---

🔧 4. How to Extend the Theme

Add a New Syntax Scope

1. Open theme-template.json.
2. Navigate to the "tokenColors" array.
3. Add a new JSON object declaring a name, scope array, and visual configurations:

   {
     "name": "New custom syntax scope",
     "scope": [
       "entity.name.tag.custom",
       "support.type.property-name.json"
     ],
     "settings": {
       "foreground": "${syntaxKeyword}",
       "fontStyle": "bold"
     }
   }
   

4. Run npm run compile to rebuild all 4 theme files.

Add a New Theme Variant (e.g., Mono-White/Paper-Phosphor)

1. Open tokens.js.
2. Duplicate an existing theme block (e.g. amber) and define your new color codes:

   white: {
     themeName: "MUTHUR-6000 White",
     uiTheme: "vs-dark",
     bg: "#080808",
     ...
   }
   

3. Open package.json and register the new theme file in "contributes.themes".
4. Open compiler.js and run it. The new theme will compile automatically!