Frontend Visual Theme Spec and Retirement of Host-Consumed Semantic CSS
This commit is contained in:
@@ -0,0 +1,85 @@
|
||||
---
|
||||
id: AGD-0037
|
||||
ticket: frontend-semantic-host-projection-flexibility
|
||||
title: Frontend Semantic Vocabulary Flexibility and Host Projection
|
||||
status: accepted
|
||||
created: 2026-05-06
|
||||
resolved: 2026-05-06
|
||||
decision: DEC-0034
|
||||
tags: [compiler, compiler-general, frontend, semantics, vscode, host-projection, lsp]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
The current discussion exposed an architectural tension:
|
||||
|
||||
- frontend semantic keys must remain frontend-owned and flexible,
|
||||
- but VS Code prefers host-shaped semantic token categories and modifiers,
|
||||
- and forcing frontend vocabularies into a rigid global taxonomy would collapse frontend ownership into host constraints.
|
||||
|
||||
If Prometeu treats VS Code semantic categories as the canonical semantic contract, the frontend loses semantic freedom and the wrong layer starts owning language meaning.
|
||||
|
||||
## Context
|
||||
|
||||
Domain owner: `compiler/general`
|
||||
|
||||
This discussion extends `DEC-0033` rather than replacing it.
|
||||
`DEC-0033` already locked that visual themes are frontend-owned and hosts are adapters.
|
||||
|
||||
What remained implicit was how a frontend-owned semantic vocabulary should adapt to host capabilities when the host prefers a different semantic model.
|
||||
|
||||
The key clarification is:
|
||||
|
||||
- the frontend semantic vocabulary remains canonical,
|
||||
- host adaptation is declarative projection,
|
||||
- host projection does not become the canonical semantic contract.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [x] Should Prometeu define a rigid global semantic token taxonomy shared by every frontend?
|
||||
R: no. Each frontend keeps its own vocabulary.
|
||||
- [x] How should VS Code consume flexible frontend vocabularies without becoming the owner of semantic meaning?
|
||||
R: through a frontend-authored host projection for VS Code.
|
||||
- [x] Does this revise `DEC-0033`?
|
||||
R: it complements `DEC-0033` by clarifying semantic vocabulary and host projection responsibilities.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Canonicalize around VS Code token types
|
||||
|
||||
- **Approach:** Force frontends to express semantic meaning in a shared VS Code-shaped taxonomy.
|
||||
- **Pro:** Simplifies host adaptation.
|
||||
- **Con:** Makes the host model canonical and removes frontend semantic freedom.
|
||||
- **Maintainability:** Poor. It solves adapter simplicity by weakening frontend ownership.
|
||||
|
||||
### Option B - Keep frontend vocabularies canonical and add declarative host projection
|
||||
|
||||
- **Approach:** Let each frontend define its own semantic keys and publish host projection metadata that explains how a host such as VS Code should adapt those keys.
|
||||
- **Pro:** Preserves frontend semantic ownership while keeping host adaptation mechanical.
|
||||
- **Con:** Requires an additional contract layer.
|
||||
- **Maintainability:** Strong. Ownership stays correct and adapters remain declarative.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Option A would make the current VS Code situation easier, but only by moving semantic authorship to the wrong layer.
|
||||
|
||||
Option B adds contract surface, but that surface is the correct one because it keeps the frontend canonical and makes host projection explicit rather than implicit.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Adopt Option B.
|
||||
|
||||
Frontend semantic keys remain canonical and flexible.
|
||||
Hosts such as VS Code consume a declarative projection authored by the frontend for that host.
|
||||
|
||||
## Discussion
|
||||
|
||||
This discussion is intentionally narrow.
|
||||
It does not reopen the frontend-owned visual theme decision.
|
||||
It only clarifies that semantic vocabulary itself must also remain frontend-owned, and that host adaptation must be expressed as projection rather than normalization into a rigid shared taxonomy.
|
||||
|
||||
## Resolution
|
||||
|
||||
Accepted on 2026-05-06.
|
||||
|
||||
Prometeu keeps frontend-owned semantic vocabularies flexible and introduces declarative host projection as the adaptation mechanism for hosts such as VS Code.
|
||||
Reference in New Issue
Block a user