Vscode Theming

Load references/module-catalog.md for: the complete key listing per module with every workbench color key and token scope assignment.

Module JSON fragment structure:

Each module produces a partial JSON object. Workbench modules produce colors entries. The syntax module produces tokenColors and semanticTokenColors entries. The assembly step merges all fragments.

{
  "colors": {
    "editor.background": "#1a1b2e",
    "editor.foreground": "#e8e6e1"
  }
}

{
  "tokenColors": [
    {
      "scope": "comment",
      "settings": { "foreground": "#8b8d98", "fontStyle": "italic" }
    }
  ],
  "semanticTokenColors": {
    "variable.readonly": "#c4b5fd"
  }
}

Isolation constraint: Each workbench color key belongs to exactly one module. No key appears in more than one module fragment. The syntax module exclusively owns tokenColors and semanticTokenColors.

</module_architecture>

Execute steps sequentially. Each step produces output that feeds the next — palette feeds semantic mapping, semantic mapping feeds module generation, modules merge into the final theme JSON.

<step_1_derive_palette>

Generate six 12-step Radix scales from the primary hex using OKLCH color space via coloraide.

Load color-derivation.instructions.md for: OKLCH-first derivation rules, Radix 12-step architecture, coloraide usage patterns, and contrast enforcement requirements.

Required scales:

Derivation rules:

• Hold hue constant within each scale — vary only L and C across the 12 steps
• Dark mode lightness range: step 1 ~L 0.13–0.15, step 12 ~L 0.93–0.97
• Chroma curve: low (steps 1–2), rising (steps 3–8), peak (steps 9–10), moderate (steps 11–12)
• Apply coloraide gamut mapping (fit('srgb')) on every OKLCH→sRGB conversion
• Output hex in 6-digit lowercase (#rrggbb), use 8-digit (#rrggbbaa) only for alpha

</step_1_derive_palette>

<step_2_map_semantic_roles>

Assign palette scale steps to semantic roles following the cross-editor mapping.

Load theme-conventions.instructions.md for: the <semantic_mapping> table and VS Code-specific format constraints.

Core role assignments:

Constraint: Every foreground/background pair formed by these assignments must pass dual-check contrast before proceeding — verify in <step_8_audit_contrast>.

</step_2_map_semantic_roles>

<step_3_generate_base_module>

Generate the base module containing core editor surface keys.

Load references/module-catalog.md for: the complete key listing for the base module.

Key assignments:

• editor.background → neutral/2
• editor.foreground → neutral/12
• editor.lineHighlightBackground → neutral/3 (subtle active line)
• editor.selectionBackground → primary/4 with alpha (#rrggbbaa)
• editor.selectionHighlightBackground → primary/3 with alpha
• editor.findMatchBackground → amber/5 with alpha
• editor.findMatchHighlightBackground → amber/4 with alpha
• editorCursor.foreground → primary/10
• editorBracketMatch.background → primary/4 with alpha
• editorBracketMatch.border → primary/8

Output: JSON fragment with colors object containing all 15 base keys.

</step_3_generate_base_module>

<step_4_generate_syntax_module>

Generate TextMate tokenColors and semanticTokenColors for syntax highlighting. This is the largest module.

Load references/module-catalog.md for: the complete scope listing and semantic type/modifier assignments for the syntax module.

TextMate tokenColors — 11 root scope groups:

Semantic token types — 21 types with foreground assignments. Use key format type: "#hex" for unmodified types and type.modifier: "#hex" for modified variants.

Semantic token modifiers — 10 modifiers. Key overrides: *.readonly adds subtle chroma shift, *.deprecated adds "strikethrough" fontStyle, *.defaultLibrary uses desaturated variant.

Output: JSON fragment with tokenColors array and semanticTokenColors object.

</step_4_generate_syntax_module>

<step_5_generate_chrome_modules>

Generate the 11 UI chrome modules as independent JSON fragments. Each module owns its workbench color keys exclusively — no key appears in more than one module.

Load references/module-catalog.md for: the complete key listing for all chrome modules.

Modules to generate:

1. activity-bar — 9 keys: bar background/foreground, active/inactive states, badge
2. sidebar — 8 keys: panel background/foreground, section headers, borders
3. tabs — 15 keys: active/inactive/hover tab states, borders, editor group headers
4. status-bar — 13 keys: bar states (normal, debugging, no-folder, remote), item states
5. panels — 10 keys: panel background, borders, title states, section headers
6. inputs-buttons — 29 keys: input fields, validation states (error/warning/info), buttons (primary/secondary), dropdowns, checkboxes
7. lists — 14 keys: selection/hover/focus states, highlights, tree guides
8. notifications — 11 keys: center/toast borders, backgrounds, icon colors
9. minimap — 11 keys: background, highlights (selection/error/warning/find), slider states, gutter
10. title-bar — 5 keys: active/inactive background/foreground, border
11. breadcrumbs — 4 keys: foreground states, picker background

Output: 11 JSON fragments, each with a colors object containing module-specific keys.

</step_5_generate_chrome_modules>

<step_6_generate_terminal_module>

Generate the terminal module with surface colors and ANSI 16 palette.

Load references/module-catalog.md for: the complete key listing for the terminal module.

Terminal surface — 6 keys: background, foreground, cursor, selection.

ANSI 16 colors — map to palette scales:

Output: JSON fragment with colors object containing 22 terminal keys.

</step_6_generate_terminal_module>

<step_7_generate_diff_git_modules>

Generate the diff-merge and git-decorations modules.

Load references/module-catalog.md for: the complete key listings for both modules.

diff-merge — 17 keys using green (inserted), red (removed), blue (incoming), and neutral (common) scales. Use alpha-transparent backgrounds (#rrggbbaa) for diff highlights to allow underlying syntax to show through.

git-decorations — 9 keys mapping git states to semantic colors: green (added), amber (modified), red (deleted), blue (renamed), neutral (ignored). Use scale step 9 for foreground colors to ensure visibility against dark tree backgrounds.

Output: 2 JSON fragments with colors objects.

</step_7_generate_diff_git_modules>

<step_8_audit_contrast>

Run WCAG 2.1 AA + APCA dual-check on all foreground/background pairs generated in steps 3–7.

Load contrast-audit/SKILL.md for: the complete pair collection, classification, calculation, and reporting workflow.

Threshold quick reference:

Remediation: When a pair fails contrast, adjust lightness in OKLCH — NEVER adjust hue or chroma to fix contrast. Increase foreground L or decrease background L until both thresholds pass.

Radix scale validation: Verify step 11 vs step 2 achieves Lc >= 60 and step 12 vs step 2 achieves Lc >= 90 for every scale.

</step_8_audit_contrast>

<step_9_validate_json>

Validate all module JSON fragments for correctness before assembly.

Syntax validation:

• Parse all JSON fragments — no trailing commas, no comments, no single quotes
• Verify all hex colors match #[0-9a-f]{6} or #[0-9a-f]{8} (6-digit or 8-digit lowercase)
• Confirm no duplicate keys across modules — each workbench color key belongs to exactly one module

Convention compliance:

• tokenColors entries have scope (string or array) and settings (object with foreground, optional fontStyle)
• semanticTokenColors keys use format type, type.modifier, or type.modifier:language
• semanticHighlighting is set to true
• Theme type is set to "dark"

Coverage completeness:

• Cross-reference generated keys against the module catalog in references/module-catalog.md
• Flag any module that has missing keys
• Verify all 16 modules have been generated

</step_9_validate_json>

<step_10_assemble_theme>

Merge all module JSON fragments into the final *-color-theme.json.

File structure:

{
  "name": "Theme Name",
  "type": "dark",
  "semanticHighlighting": true,
  "colors": { },
  "tokenColors": [ ],
  "semanticTokenColors": { }
}

Assembly rules:

1. Merge all module colors objects into the top-level colors — keys must not conflict
2. Concatenate tokenColors array from the syntax module into the top-level tokenColors
3. Merge semanticTokenColors object from the syntax module into the top-level semanticTokenColors
4. Set name, type: "dark", and semanticHighlighting: true

Package manifest — package.json must include:

{
  "contributes": {
    "themes": [
      {
        "label": "Theme Name",
        "uiTheme": "vs-dark",
        "path": "./themes/theme-name-color-theme.json"
      }
    ]
  },
  "categories": ["Themes"]
}

Output verification: Parse the assembled JSON, confirm no duplicate keys, and verify the theme loads in VS Code without errors.

</step_10_assemble_theme>

<important_rules>

Critical rules that govern all VS Code theme generation. Violations cause broken themes or inconsistent output.

• Hex format — All color values as 6-digit lowercase hex #rrggbb. Use 8-digit #rrggbbaa only for alpha transparency (selections, highlights, diff backgrounds). No shorthand, no uppercase, no named colors
• OKLCH-only derivation — All colors derive from the primary hex via OKLCH. Cross-reference color-derivation.instructions.md for pipeline rules. No hardcoded hex values anywhere
• Module isolation — Each workbench color key belongs to exactly one module. No key appears in more than one module fragment. The syntax module exclusively owns tokenColors and semanticTokenColors
• Semantic highlighting required — ALWAYS set semanticHighlighting: true to enable language-aware token coloring over TextMate fallbacks
• Dark type required — ALWAYS set type: "dark" so VS Code applies the correct base theme defaults for uncustomized keys
• No trailing commas — VS Code theme JSON does not allow trailing commas. Validate all fragments parse correctly
• Token scope specificity — More specific scopes override less specific ones. Order tokenColors from general to specific so overrides work correctly
• Module catalog — The complete key reference is in references/module-catalog.md. JIT-load this file when generating module content — do not memorize or inline the full catalog

</important_rules>

<error_handling>

• If a contrast check fails on a foreground/background pair, then adjust the foreground lightness (L) in OKLCH — increase L for light-on-dark. Never adjust hue or chroma to fix contrast. Re-run dual-check after adjustment
• If a workbench color key is not recognized by VS Code, then verify against the latest VS Code API documentation — deprecated keys should be replaced with their successors, not silently included
• If JSON validation reports a syntax error, then check for trailing commas, missing quotes, or malformed hex values. Common in generated JSON: trailing comma on last entry in object/array
• If duplicate keys are found across modules, then assign the key to the module where it semantically belongs and remove from the other
• If a semantic token type has no color assignment, then inherit from the closest TextMate scope — semantic tokens fall back to TextMate scopes when unset
• If the assembled theme does not load in VS Code, then verify: package.json has correct contributes.themes path, JSON parses without errors, type is "dark", file extension is .json

</error_handling>

P1 — Blocking (must pass before delivery):

• All 16 modules generated with complete key assignments per module catalog
• All tokenColors entries have valid scope and settings with foreground
• All semanticTokenColors entries use valid type.modifier:language key format
• semanticHighlighting: true and type: "dark" present in assembled theme
• No duplicate workbench color keys across modules
• All hex values are 6-digit or 8-digit lowercase format
• No hardcoded colors — every value traces to the OKLCH pipeline
• All foreground/background pairs pass WCAG 2.1 AA + APCA dual-check
• Assembled JSON parses without errors

P2 — Quality (should pass):

• All 11 TextMate root scope groups have tokenColors entries
• All 21 semantic token types have semanticTokenColors entries
• Terminal ANSI 16 colors complete with all normal/bright pairs
• package.json manifest includes correct contributes.themes configuration
• Radix scale step 11 vs step 2 achieves Lc >= 60 for all scales
• Radix scale step 12 vs step 2 achieves Lc >= 90 for all scales

P3 — Polish (nice to have):

• Semantic token modifiers *.readonly, *.deprecated, *.defaultLibrary have distinct styling
• Diff backgrounds use alpha transparency to preserve syntax visibility
• Body text pairs reach preferred APCA Lc 90 (not just minimum Lc 75)
• Git decoration colors are distinct from each other at a glance
• Minimap highlights use perceptually distinct colors for error vs warning vs find match

• color-derivation.instructions.md — OKLCH pipeline rules, Radix scale architecture, coloraide usage, contrast enforcement
• theme-conventions.instructions.md — <semantic_mapping> table, VS Code format constraints, file naming conventions
• contrast-audit/SKILL.md — Contrast verification workflow: pair collection, classification, WCAG + APCA calculation, gap detection, reporting
• references/module-catalog.md — Complete workbench color key and token scope listing per module (JIT-load when generating module content)
• tools/generate_radiant_theme.py — Reference implementation: OKLCH palette derivation → module-based theme generation (~2250 lines)
• extensions/vscode/themes/dark-radiant-teal-theme.json — Reference output: complete color-theme.json with 887 workbench, 119 token, and 78 semantic entries