153 lines
7.3 KiB
Markdown
153 lines
7.3 KiB
Markdown
---
|
|
id: DEC-0033
|
|
ticket: frontend-visual-theme-spec-and-css-retirement
|
|
title: Frontend-owned visual theme spec as canonical presentation contract
|
|
status: accepted
|
|
created: 2026-05-06
|
|
accepted: 2026-05-06
|
|
agenda: AGD-0036
|
|
plans: [PLN-0068, PLN-0069, PLN-0070, PLN-0071]
|
|
tags: [compiler, compiler-general, frontend, presentation, theming, studio, vscode, lsp, pbs]
|
|
---
|
|
|
|
## Decision
|
|
|
|
Prometeu SHALL replace frontend-authored host-consumed semantic CSS with a structured frontend-owned visual theme specification as the canonical presentation contract.
|
|
|
|
This decision locks the following normative points:
|
|
|
|
1. Each `FrontendSpec` MUST publish its own semantic vocabulary and MAY publish multiple visual themes for that vocabulary.
|
|
2. Visual themes MUST be frontend-owned and MUST remain associated with the semantic tokens defined by that same frontend.
|
|
3. `semantic-highlighting.css` MUST be treated as migration input only and MUST cease to be an authored canonical contract by the end of this refactor.
|
|
4. Studio and the VS Code extension MUST act as rendering adapters over the frontend-owned visual contract and MUST NOT become owners of frontend theme data.
|
|
5. The VS Code extension MUST translate the frontend visual contract dynamically or mechanically from the contract itself, so frontend visual adjustments do not require extension maintenance for each theme change.
|
|
|
|
## Rationale
|
|
|
|
The current model is structurally weak for multi-host consumption.
|
|
PBS still carries a CSS resource that works as the practical source of visual truth, while VS Code can only consume a partial manual approximation through semantic token configuration.
|
|
|
|
That creates the wrong ownership boundary:
|
|
|
|
1. the frontend owns semantic meaning but does not fully own its exported visual contract;
|
|
2. hosts are forced to reinterpret or approximate visual intent;
|
|
3. every frontend visual adjustment risks requiring host edits;
|
|
4. visual drift becomes likely across Studio and VS Code.
|
|
|
|
The repository already established that semantic presentation belongs to the frontend.
|
|
This decision extends that ownership model into a stronger cross-host contract:
|
|
|
|
1. the frontend authors semantic and visual intent once;
|
|
2. LSP transports that intent;
|
|
3. hosts adapt it without redefining it.
|
|
|
|
## Technical Specification
|
|
|
|
### 1. Canonical Visual Contract
|
|
|
|
`FrontendSpec` MUST evolve to expose a structured visual presentation contract as canonical data.
|
|
|
|
That contract MUST:
|
|
|
|
1. live with the frontend definition;
|
|
2. be versioned together with `FrontendSpec`;
|
|
3. be sufficient for multiple hosts to render the frontend's intended appearance without interpreting CSS as the source of truth;
|
|
4. remain compiler-general even if PBS is the first frontend to implement it.
|
|
|
|
The canonical contract MAY be encoded as JSON-backed structured data or as an equivalent strongly-typed model, but the authored source of truth MUST be the structured visual contract, not CSS.
|
|
|
|
### 2. Frontend-Owned Themes
|
|
|
|
Each frontend MAY publish multiple visual themes.
|
|
|
|
Rules:
|
|
|
|
1. themes MUST belong to the frontend that defines the semantic vocabulary they style;
|
|
2. themes MUST be expressed in terms of that frontend's own semantic token keys and related editor presentation surfaces;
|
|
3. hosts MAY select which frontend theme is active;
|
|
4. hosts MUST NOT redefine the theme contract as host-owned authored data.
|
|
|
|
This means theme ownership is:
|
|
|
|
1. frontend authors themes,
|
|
2. host selects and applies themes,
|
|
3. host does not author the frontend visual semantics.
|
|
|
|
### 3. Token-Centric Contract with Editor Surfaces
|
|
|
|
The visual contract MUST be token-centric, but it SHALL also support editor-level presentation data where needed to preserve frontend visual intent.
|
|
|
|
Therefore the contract MUST be able to express:
|
|
|
|
1. token-scoped presentation such as foreground, emphasis, and related token styling attributes;
|
|
2. editor surface colors such as base foreground, selection, gutter, and other editing-surface colors when they are part of frontend visual intent;
|
|
3. optional frontend-specific accents tied to the editing experience.
|
|
|
|
Token-centricity remains mandatory because semantic meaning MUST stay anchored to semantic keys.
|
|
Editor-surface data is allowed because semantic fidelity alone is insufficient to reproduce frontend identity across hosts.
|
|
|
|
### 4. Host Adapter Responsibilities
|
|
|
|
Studio and the VS Code extension MUST consume the frontend visual contract as adapters.
|
|
|
|
Studio:
|
|
|
|
1. MUST consume the structured frontend visual contract;
|
|
2. MAY render through generated CSS or another host mechanism;
|
|
3. MUST NOT treat generated CSS as the canonical frontend artifact.
|
|
|
|
VS Code extension:
|
|
|
|
1. MUST consume the frontend visual contract through the server description path or an equivalent frontend-owned transport surface;
|
|
2. MUST translate that contract into whatever VS Code requires, whether through runtime translation, generated contributions, or another adapter mechanism;
|
|
3. MUST behave as a mechanical translator of the frontend contract;
|
|
4. MUST NOT require hand-maintained extension theme edits whenever a frontend changes a color, emphasis rule, or theme variant.
|
|
|
|
### 5. LSP Transport Responsibilities
|
|
|
|
The LSP path MUST transport enough structured frontend-owned visual information for hosts to render the active frontend theme.
|
|
|
|
It MUST preserve:
|
|
|
|
1. frontend identity,
|
|
2. semantic token identity,
|
|
3. theme identity where multiple themes exist,
|
|
4. visual attributes needed by the host adapter.
|
|
|
|
LSP MUST NOT collapse frontend themes into host-authored generic theme categories.
|
|
|
|
### 6. Migration and CSS Retirement
|
|
|
|
`semantic-highlighting.css` is allowed only as migration input for the first structured contract derivation.
|
|
|
|
Migration rules:
|
|
|
|
1. PBS SHALL be the first frontend migrated;
|
|
2. the existing PBS CSS MAY be parsed or manually transcribed into the first canonical structured visual contract;
|
|
3. once the structured contract becomes authoritative, the CSS MUST no longer be treated as authored truth;
|
|
4. any remaining CSS after migration MAY exist only as generated adapter output or as temporary compatibility residue scheduled for removal;
|
|
5. the refactor is not complete while host-consumed semantic CSS remains the canonical frontend presentation source.
|
|
|
|
### 7. Extension Stability Requirement
|
|
|
|
This decision explicitly locks an operational requirement for `tools/vscode-extension`:
|
|
|
|
1. frontend visual changes MUST be expressible by changing frontend-owned contract data;
|
|
2. such frontend changes MUST NOT force routine extension source edits;
|
|
3. the extension SHALL be stable as a contract adapter rather than a repository of manually curated frontend theme rules.
|
|
|
|
## Constraints
|
|
|
|
1. The canonical source of frontend visual intent MUST move out of authored CSS.
|
|
2. Theme ownership MUST remain with the frontend.
|
|
3. The contract MUST support multiple themes per frontend.
|
|
4. The contract MUST remain compiler-general and MUST NOT hardcode PBS as the universal model.
|
|
5. Hosts MUST remain adapters and MUST NOT become fallback authors of frontend visual identity.
|
|
6. Any derived plan MUST include an explicit migration path for PBS and explicit retirement of `semantic-highlighting.css` as canonical data.
|
|
7. Any derived plan MUST cover compiler contract changes, transport propagation, Studio consumption, and VS Code consumption.
|
|
|
|
## Revision Log
|
|
|
|
- 2026-05-06: Initial accepted decision from AGD-0036.
|
|
- 2026-05-06: Decomposed into PLN-0068, PLN-0069, PLN-0070, and PLN-0071.
|