94 lines
3.8 KiB
Markdown
94 lines
3.8 KiB
Markdown
---
|
|
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
|