prometeu-studio/discussion/workflow/agendas/AGD-0036-frontend-visual-theme-spec-and-css-retirement.md

---
id: AGD-0036
ticket: frontend-visual-theme-spec-and-css-retirement
title: Frontend Visual Theme Spec and Retirement of Host-Consumed Semantic CSS
status: accepted
created: 2026-05-06
resolved: 2026-05-06
decision: DEC-0033
tags: [compiler, compiler-general, frontend, presentation, theming, studio, vscode, lsp, pbs]
---

## Pain

The current semantic highlighting path is no longer strong enough now that Prometeu must project frontend-owned presentation into more than one host.

Today the frontend still effectively ships a host-facing CSS file as the practical source of truth for visual presentation.
That works tolerably for the legacy Studio editor path, but it collapses once the same frontend presentation must be exported to VS Code through LSP semantic tokens.

The result is a weak cross-host contract:

- the frontend publishes semantic keys, but not a complete visual spec,
- `semantic-highlighting.css` still acts as the real authored presentation artifact,
- VS Code only receives a partial hand-translated approximation,
- and each host risks drifting away from the frontend's intended visual identity.

The CSS file should be treated as migration input only and must die by the end of this refactor.

## Context

Domain owner: `compiler/general`

Propagation targets are expected in at least three places:

- compiler frontend metadata and contracts,
- Studio host consumption,
- VS Code extension host consumption.

Relevant historical context already exists in `LSN-0029`, which established frontend ownership of semantic presentation metadata through `FrontendSpec`.
That lesson is still useful for ownership boundaries, but it is not sufficient for the next wave because the current contract is too weak and too resource-oriented.

Current state:

- `FrontendSemanticPresentationSpec` exposes only `semanticKeys` and opaque `resources`,
- PBS publishes `/themes/pbs/semantic-highlighting.css` as a semantic presentation resource,
- Studio can consume that resource directly,
- VS Code cannot consume that CSS directly and must approximate it via `package.json` and semantic token theming,
- recent LSP work now transports PBS semantic token types, but the host-side rendering still falls short of the original PBS editor look.

What is missing is a frontend-owned visual spec that is structured enough to be exported to multiple hosts without making CSS the canonical source.

## Open Questions

- [x] What is the canonical replacement for `semantic-highlighting.css` inside `FrontendSpec`?
  R: a structured visual presentation spec (a JSON) that includes semantic token styles and editor-level colors.
- [x] Which parts of frontend presentation are normative and cross-host, and which are host-specific adapters only?
  R: a ideia eh que o FE presentation possa ser completamente expostado para os clientes como o VSCode.
- [x] Should the visual contract be semantic-token-centric only, or should it also include editor-level colors such as base foreground, selection, gutter, and accent surfaces?
  R: o contrato visual pode ofertar toda essa gama de atributos para cada token, o cliente (VSCode) pode usa-los para compor o tema, mas o contrato deve ser token-centric para garantir que a intenção visual seja sempre atrelada a chaves semânticas.
- [x] How should Studio consume the new visual spec without keeping CSS as a hidden canonical source?
  R: o FE Presentation na medida que o servidor eh described oferece um contrato visual estruturado, o cliente (VSCode extension) deve consumir esse contrato e gerar o que tiver que gerar para compor o tema. Se o cliente usar CSS que gere isso.
- [x] How should VS Code consume the new visual spec: static generated contribution, runtime translation, or both?
  R: A ideia eh que o cliente seja bem burro, ele deve ser uma maquina que traduz o contrato visual para um formato que o VSCode entenda, seja isso um contribution estatico ou uma tradução dinamica, o importante eh que o contrato visual seja o unico input e a fonte de verdade para a intencao visual do frontend.
- [x] How do we phase out existing frontend-owned CSS resources without breaking current Studio rendering during migration?
  R: nada no studio depende desse CSS, ele eh um artefato de migração para o PBS. O contrato visual deve ser definido e implementado no PBS primeiro, usando o CSS como input para derivar o formato estruturado. Depois disso, o CSS pode ser descontinuado.
- [x] How do we version and validate the visual contract so new frontends can implement it consistently?
  R: o contrato deve viver dentro de `FrontendSpec` e ser versionado junto com ele.

## Options

### Option A - Keep CSS as the canonical frontend artifact and add exporters around it

- **Approach:** Preserve `semantic-highlighting.css` as the frontend-owned source and build tooling that parses or translates it into Studio and VS Code outputs.
- **Pro:** Smallest migration cost in the short term, because PBS already has authored CSS.
- **Con:** Keeps host-facing CSS as the source of truth, which is the wrong abstraction for multi-host consumption and weak for validation.
- **Maintainability:** Poor. Every new host would need a CSS interpretation path or a CSS-to-host adapter with lossy translation rules.

### Option B - Introduce a structured frontend visual spec and treat CSS as a temporary migration input

- **Approach:** Replace the current resource-centric semantic presentation contract with a structured visual spec published by the frontend. Use the existing CSS only as bootstrap input while migrating PBS, then retire it as canonical data.
- **Pro:** Creates a real multi-host contract that can be exported mechanically to Studio and VS Code while preserving frontend ownership.
- **Con:** Requires contract design, adapter work in both hosts, and a migration story for current frontend resources.
- **Maintainability:** Strong. New frontends would author one canonical visual contract and hosts would implement stable adapters.

### Option C - Split the contract into semantic vocabulary plus host-owned themes

- **Approach:** Keep frontend ownership only over semantic keys and let each host define its own visual theme for those keys.
- **Pro:** Simplifies frontend metadata and gives each host more freedom.
- **Con:** Reintroduces host ownership over frontend meaning in practice and guarantees visual drift between Studio and VS Code.
- **Maintainability:** Medium at best. It reduces frontend burden but loses the core requirement of frontend-owned identity.

## Tradeoffs

Option A looks attractive because it reuses existing assets, but it cements the wrong boundary.
If CSS remains canonical, the compiler/frontend layer still cannot describe its own presentation in a host-neutral way.

Option C is cleaner than the current situation from a tooling perspective, but it fails the product goal.
The user experience would vary per host because visual meaning would no longer be frontend-owned.

Option B is the only direction that preserves the previous ownership decision while extending it into a credible cross-host architecture.
Its cost is real, but that cost is exactly the work we need to make the contract durable.

## Recommendation

Adopt Option B.

The frontend should publish a structured visual presentation spec as canonical data.
That spec should become the only normative source for frontend semantic/editor appearance that is intended to survive across hosts.

`semantic-highlighting.css` should be used only as migration input for PBS while we derive the first structured visual spec.
After migration, CSS may remain as a generated Studio adapter artifact for a while, but it must no longer be treated as authored truth.

The new contract likely needs at least these conceptual layers:

- semantic token styles,
- editor surface colors,
- optional UI accent colors tied to the editing surface,
- explicit host adapter boundaries.

The LSP path should transport structured visual data or enough structured metadata for the VS Code extension to render the same frontend-owned intent without reverse-engineering CSS.

## Discussion

This agenda is intentionally narrower than “general editor theming”.
The problem is not to invent a universal Prometeu theme engine first.
The problem is to stop using frontend-authored CSS as the canonical semantic/editor presentation contract and replace it with a frontend-owned visual spec that survives host translation.

The most important discipline point is ownership:

- compiler/frontend owns semantic and visual intent,
- LSP transports frontend-owned intent,
- Studio and VS Code are rendering adapters,
- host adapters may have capability gaps, but they must not become canonical.

There is also an important migration constraint:

- PBS is the first frontend and will define the initial shape,
- but the contract must not become “PBS-specific metadata with generic naming later”,
- instead it must be valid as a compiler-general surface that PBS implements first.

## Resolution

Accepted on 2026-05-06.

The discussion resolves in favor of a structured frontend-owned visual theme specification with support for multiple themes per frontend.
Themes remain tied to the frontend's own semantic vocabulary.
Studio and the VS Code extension act as adapters over that contract.
`semantic-highlighting.css` remains migration input only and must be retired as canonical authored truth.