---
id: PLN-0071
ticket: frontend-visual-theme-spec-and-css-retirement
title: VS Code Dynamic Theme Translation Adapter
status: open
created: 2026-05-06
completed:
tags: [vscode, extension, lsp, presentation, theming, adapter]
---

## Objective

Turn the VS Code extension into a stable adapter that translates frontend-owned visual theme contracts into VS Code-compatible rendering behavior without requiring source edits for routine frontend theme changes.

## Background

`DEC-0033` explicitly locks that the extension must not become a repository of manually curated frontend theme rules. The extension must translate the contract it receives rather than being edited whenever a frontend changes colors, emphasis, or theme variants.

This plan covers the client-side adapter behavior that satisfies that requirement.

## Scope

### Included
- Replace hardcoded per-frontend visual theme rules with dynamic or generated translation based on the transported frontend contract.
- Define the minimum static VS Code contribution surface still required by the platform.
- Support multi-theme frontend data consumption and active-theme application.
- Add extension tests or verification coverage around theme translation.

### Excluded
- Compiler-side contract definition.
- LSP transport definition.
- Studio rendering behavior.

## Non-Goals

- Building a general-purpose VS Code theme marketplace artifact.
- Allowing the extension to become a second authored source of frontend theme truth.
- Solving unrelated reconnect or transport lifecycle issues beyond what this adapter needs.

## Execution Steps

### Step 1 - Identify the minimal static VS Code contribution surface

**What:** Separate what the extension must declare statically from what it can translate dynamically.
**How:** Keep only the minimal `package.json` contribution data required for VS Code to recognize semantic token kinds or activate the extension. Remove hardcoded frontend-specific color rules from static configuration where dynamic translation can take over.
**File(s):** `tools/vscode-extension/package.json`, related extension bootstrap files.

### Step 2 - Implement contract-to-VS Code theme translation

**What:** Translate frontend-owned visual contract data into VS Code-understandable configuration.
**How:** Update extension runtime code to receive the transported visual theme contract, map token and editor-surface data into the VS Code APIs/configuration model, and apply the active frontend theme deterministically.
**File(s):** `tools/vscode-extension/src/**`, mirrored build outputs only if local toolchain constraints require temporary manual sync.

### Step 3 - Support multi-theme frontends without extension source edits

**What:** Make frontend theme growth operationally cheap.
**How:** Ensure that adding or changing frontend-owned themes does not require new extension source logic unless the VS Code platform itself introduces a new capability boundary. Theme identity, token rules, and active selection must be data-driven.
**File(s):** `tools/vscode-extension/src/**`, possible supporting protocol model surfaces if consumed directly.

### Step 4 - Add adapter verification coverage

**What:** Protect the no-manual-theme-maintenance rule.
**How:** Add tests or deterministic verification around:

1. translation of token rules,
2. translation of editor-surface colors where supported,
3. handling of multiple frontend themes,
4. absence of hardcoded PBS-only theme logic in the adapter path.

**File(s):** `tools/vscode-extension/src/test/**` if present, or equivalent test harness/verification approach adopted by the extension module.

## Test Requirements

### Unit Tests
- Validate translation of structured token rules into VS Code-compatible theme rules.
- Validate active-theme switching behavior for data-driven frontend themes.

### Integration Tests
- Run extension-targeted validation proving the frontend contract can change without source-level theme edits.

### Manual Verification
- Open PBS content through the extension and confirm the active theme is applied from transported contract data rather than hardcoded `package.json` color tables.

## Acceptance Criteria

- [ ] The extension no longer depends on hardcoded frontend-specific theme rules as the primary rendering source.
- [ ] Frontend theme changes are driven by contract data rather than extension source edits.
- [ ] Multi-theme frontend payloads can be translated and applied deterministically.
- [ ] The remaining static VS Code contribution surface is minimal and structural only.

## Dependencies

- `DEC-0033` accepted and normatively locked.
- `PLN-0069` for transport of visual theme data to the extension.

## Risks

- VS Code platform constraints may force a hybrid static/runtime model that must stay carefully bounded.
- The current local Node/TypeScript environment issues can slow validation.
- Leaving too much theme data in `package.json` would preserve the current maintenance problem under a new name.