---
id: PLN-0068
ticket: frontend-visual-theme-spec-and-css-retirement
title: Frontend Visual Contract and PBS Migration
status: open
created: 2026-05-06
completed:
tags: [compiler, compiler-general, frontend, pbs, presentation, theming, contract]
---

## Objective

Introduce the canonical structured frontend visual contract in `FrontendSpec`, migrate PBS to that contract, and demote `semantic-highlighting.css` from authored truth to migration-only input.

## Background

`DEC-0033` locks that frontend visual intent must become structured canonical data, support multiple themes per frontend, remain token-centric, and retire authored host-consumed semantic CSS as the canonical source.

PBS is the first frontend and therefore defines the first concrete migration path, but the contract MUST remain compiler-general rather than PBS-shaped by accident.

## Scope

### Included
- Evolve compiler/frontend metadata to publish a structured visual contract.
- Define the contract shape for semantic-token styling, editor surfaces, and theme identity.
- Migrate PBS to the new contract.
- Preserve any temporary migration utility needed to derive the first contract from the existing PBS CSS.
- Add validation tests that make the new contract normative and stable.

### Excluded
- LSP transport changes.
- Studio rendering changes.
- VS Code runtime translation changes.

## Non-Goals

- Designing a generic host-owned theme engine.
- Supporting every possible frontend visual attribute in wave 1.
- Keeping authored CSS as a parallel canonical source.

## Execution Steps

### Step 1 - Define the structured visual contract in compiler-general surfaces

**What:** Replace the resource-centric semantic presentation shape with a canonical structured visual contract in `FrontendSpec`.
**How:** Add or evolve frontend metadata models so each frontend can publish:

1. semantic token vocabulary ownership,
2. one or more named visual themes,
3. token-centric visual rules,
4. editor-surface colors needed to preserve frontend identity.

The model MUST be compiler-general and MUST NOT encode PBS-specific assumptions into the shared type system.
**File(s):** `prometeu-compiler/prometeu-compiler-core/src/main/java/p/studio/compiler/models/**`, affected frontend registry/definition surfaces.

### Step 2 - Define the theme and token rule semantics explicitly

**What:** Make the contract operational rather than descriptive.
**How:** Specify exact fields, invariants, and null/empty behavior for:

1. theme identity,
2. theme selection metadata if needed at the contract layer,
3. token style rules,
4. editor surface colors,
5. versioning semantics inside or alongside `FrontendSpec`.

The implementation MUST make it possible for hosts to translate the contract mechanically without inferring missing meaning.
**File(s):** `prometeu-compiler/prometeu-compiler-core/src/main/java/**`, associated tests in compiler modules.

### Step 3 - Migrate PBS from authored CSS truth to structured contract truth

**What:** Make PBS the first frontend to author the new contract.
**How:** Update `PBSDefinitions` and related PBS presentation metadata to publish one or more frontend-owned themes through the new contract. The existing `semantic-highlighting.css` MAY be parsed or manually transcribed to bootstrap the migration, but once the structured contract is in place, CSS MUST no longer be treated as authored truth.
**File(s):** `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/**`, `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/themes/pbs/**`, related PBS tests.

### Step 4 - Lock contract validity with tests

**What:** Prevent future drift back to opaque resource ownership.
**How:** Add tests that assert:

1. frontends publish structured visual themes,
2. PBS token vocabulary and theme definitions are coherent,
3. required token styles and editor-surface data resolve correctly,
4. authored CSS is no longer the canonical contract source.

**File(s):** compiler-general and PBS test suites.

## Test Requirements

### Unit Tests
- Validate model invariants for theme IDs, token rules, and editor-surface fields.
- Validate `FrontendSpec` copies and exposes structured theme data safely.
- Validate PBS publishes at least one coherent theme using the new contract.

### Integration Tests
- Run targeted compiler and PBS tests proving the contract compiles, resolves, and remains discoverable through frontend definitions.

### Manual Verification
- Inspect the PBS frontend definition and confirm the structured contract is the readable authored source of truth.
- Confirm any remaining CSS is clearly migration-only or generated-output-only.

## Acceptance Criteria

- [ ] `FrontendSpec` publishes a structured canonical visual contract.
- [ ] The contract supports multiple themes per frontend.
- [ ] The contract is token-centric and can also express editor-surface colors.
- [ ] PBS is migrated to the new contract.
- [ ] `semantic-highlighting.css` is no longer treated as authored canonical frontend presentation data.

## Dependencies

- `DEC-0033` accepted and normatively locked.

## Risks

- Overfitting the first contract to PBS would weaken future frontend adoption.
- An underspecified token-style model would force host inference and violate the decision.
- Keeping CSS alive as a silent parallel truth source would nullify the migration.