prometeu-studio/discussion/lessons/DSC-0033-frontend-visual-theme-spec-and-css-retirement/LSN-0050-frontend-owned-visual-themes-with-structured-contract-and-host-adapters.md

id	discussion	title	status	created	updated	tags
LSN-0050	DSC-0033	Frontend-owned visual themes with structured contract and host adapters	done	2026-05-08	2026-05-08	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