Intrepid/prometeu-studio
Intrepid/prometeu-studio
4
0
Fork 0
Code Pull Requests Activity
prometeu-studio/discussion/workflow/decisions/DEC-0033-frontend-visual-theme-spec-and-css-retirement.md

7.3 KiB
Raw Blame History

id ticket title status created accepted agenda plans tags
DEC-0033 frontend-visual-theme-spec-and-css-retirement Frontend-owned visual theme spec as canonical presentation contract accepted 2026-05-06 2026-05-06 AGD-0036
PLN-0068
PLN-0069
PLN-0070
PLN-0071
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.