---
id: LSN-0050
discussion: DSC-0033
title: Frontend-owned visual themes with structured contract and host adapters
status: done
created: 2026-05-08
updated: 2026-05-08
tags: [compiler, compiler-general, frontend, presentation, theming, lsp, vscode, pbs]
---

## Original Problem

Frontend semantic presentation was frontend-owned in principle, but not in a form that could survive multiple hosts.

PBS still depended on authored semantic CSS as the practical visual source of truth, which created three problems:

- CSS was a host-facing artifact rather than a compiler-general contract;
- VS Code could only approximate frontend intent through manual translation;
- every host risked drifting away from the frontend's real visual identity.

## Consolidated Decision

`DEC-0033` replaced authored host-consumed semantic CSS with a structured frontend-owned visual contract.

That contract now owns:

- the frontend theme list;
- the default active theme;
- token-scoped styles;
- editor-surface palette data;
- and host projections used to translate frontend semantic keys into host-native semantic selectors.

Hosts are adapters over this data.
They do not own frontend visual truth.

## Final Result

The canonical visual source now lives in `FrontendSemanticPresentationSpec`, with concrete PBS theme data and host projections authored in structured Java models instead of CSS resources.

The new LSP path transports:

- frontend semantic keys;
- visual themes;
- active theme identity;
- and host projection metadata.

The VS Code extension consumes that payload and writes semantic token and workbench color customizations dynamically, which means routine frontend color changes no longer require hand-edited extension theme tables.

The old PBS semantic CSS still exists only as migration residue and derivative compatibility material.
It is no longer the authored canonical contract.

## Implementation Notes

The decision was realized across four layers:

1. compiler/frontend metadata grew a structured presentation contract;
2. PBS migrated its theme definition into that contract;
3. the LSP description path started exporting visual themes and host projections;
4. the VS Code extension became a mechanical translator of the contract at runtime.

This also clarified the relationship between `DSC-0033` and `DSC-0034`:

- `DSC-0033` established the structured theme contract and CSS retirement;
- `DSC-0034` established that host projections belong in the frontend contract rather than in the host.

Together they define the current highlight pipeline.

## Example

For PBS today:

- the frontend publishes semantic keys such as `pbs-keyword` and `pbs-service`;
- the same frontend publishes the canonical theme colors and emphasis flags for those keys;
- the LSP sends the theme plus a `vscode` host projection;
- the VS Code extension applies both the canonical semantic selectors and the projected host selectors.

This is why a color change in PBS theme data can flow to VS Code without a new curated palette in `package.json`.

## Pitfalls and Anti-Patterns

- Do not reintroduce CSS as a silent second source of truth.
- Do not move frontend theme authorship into host adapters just because one host has capability gaps.
- Do not collapse frontend semantic identity into generic host categories during transport; host categories are projections, not the canonical vocabulary.

## References

- `AGD-0036` Frontend Visual Theme Spec and Retirement of Host-Consumed Semantic CSS
- `DEC-0033` Frontend-owned visual theme spec as canonical presentation contract
- `PLN-0068` Frontend Visual Contract and PBS Migration
- `PLN-0069` LSP Visual Theme Transport and Theme Selection Propagation
- `PLN-0070` Studio Visual Theme Adapter and CSS Retirement
- `PLN-0071` VS Code Dynamic Theme Translation Adapter
- `LSN-0048` Frontend-owned semantic vocabularies with declarative host projection