Skin V1 Surface Grammar and complete UI continuity governance

[BryanHarrisScripts]

Objective

Make PlotPickle's Skin V1 user experience visually deterministic across every meaningful reachable surface, including nested Community, Library, Settings and production flows.

The problem is no longer a handful of isolated CSS defects. The Human review found structural drift across the product: return controls change side, borders/trim appear inconsistently, title/header geometry varies, content widths drift, green/palette treatment differs, and some nested screens are not represented in the standard visual verification set.

The governing fix is:

One Surface Registry + one Surface Grammar + one upgraded UI Continuity Agent + CI blockers for structural drift.

Dashboard remains the canonical visual reference, but consistency must be enforced through deterministic geometry/token/structure contracts rather than screenshot similarity alone.

Findings driving this issue

1. config/ui-continuity-agent-registry.json is stale and still declares matte-black-teal-orange rather than the current Skin V1 Matrix vocabulary.
2. UI Continuity and WebMCP maintain separate screen inventories.
3. The existing UI Continuity Agent checks broad shell/navigation/theme properties but does not enforce page grammar such as return-control side, header geometry, title position, content measure, trim, border treatment, panel framing or structural spacing.
4. Visual Director currently treats many visible consistency defects as advisories, including palette, spacing rhythm, hierarchy and width drift.
5. The standard WebMCP catalogue captures a useful set of surfaces, but does not prove that every meaningful nested state reachable in the product is represented.
6. Screenshot baselines remain useful regression evidence but cannot be the primary structural consistency mechanism because platform rasterization can vary while geometry and tokens can be deterministic.

Contract

One canonical Surface Registry

Create one canonical registry consumed by UI Continuity, WebMCP/Visual Director and related verification. Each surface entry must be able to declare:

• stable id and label;
• route/navigation path;
• parent surface;
• surface class;
• canonical root/ready selectors where applicable;
• return path;
• capture policy and current visual-governance state;
• expected area/destination where applicable;
• whether it is a public/startup exception.

No verifier should maintain an independent authoritative inventory.

Skin V1 Surface Grammar

Codify the reusable visual structure rather than leaving it implicit in screenshots. At minimum the grammar must cover:

• canonical application/content measure;
• page-header geometry;
• title position/hierarchy;
• return-control side, geometry and treatment;
• border/trim vocabulary;
• panel framing;
• Skin V1 palette/token provenance;
• 4px spacing rhythm;
• control-height rhythm;
• nested-surface parent/child presentation;
• empty-state presentation;
• allowed surface-class exceptions.

Surface classes may differ in content and internal workflow, but the same class must obey the same structural grammar.

UI Continuity Agent

Upgrade the existing agent; do not create another agent.

It should inspect rendered geometry and token provenance for the grammar above and compare a surface against its declared class. Mechanical violations should be deterministic findings.

The agent remains bounded: it must not invent UX, mutate story/canon or silently redesign ambiguous surfaces.

CI severity

Promote structural drift to blockers for Experience Skins verification, including at least:

• wrong return-control side/placement;
• missing or unexpected standard header frame;
• materially wrong content measure for the declared class;
• noncanonical structural border/trim;
• non-token structural colours where a Skin V1 token exists;
• off-grid structural padding/spacing;
• title/header hierarchy outside the declared class contract;
• unregistered meaningful reachable surfaces.

Minor rasterization and intentionally documented exceptions can remain advisory.

Implementation sequence

Phase 0 — Ground-zero contract and census

• Add the developer brief for this issue.
• Define the canonical Skin V1 Surface Grammar.
• Define the canonical Surface Registry schema and initial inventory.
• Retire stale matte-black-teal-orange continuity vocabulary.
• Mark all known nested surfaces, including Community children, even if some begin as census-only entries pending capture selectors.
• Add tests proving the old duplicate inventory cannot silently diverge.

Phase 1 — One registry consumed by verification

• Make UI Continuity consume the canonical registry.
• Make WebMCP/Visual Director consume the same canonical registry or a deterministic projection of it.
• Remove duplicate authoritative inventory ownership.
• Preserve existing navigation/capture behavior while changing ownership.

Phase 2 — Structural grammar measurements

• Capture header rectangle and structural role.
• Capture return-control rectangle, side and treatment.
• Capture title rectangle/baseline and hierarchy role.
• Capture root/content measure.
• Capture border/trim and panel-frame treatment.
• Capture structural padding/spacing and control-height rhythm.
• Capture token provenance/approved resolved palette.
• Compare against declared surface class.

Phase 3 — CI blocker policy

• Convert structural grammar violations from advisory to blocker/error.
• Keep documented class-specific exceptions explicit in the registry/grammar.
• Add focused regression tests for left/right return drift, missing border/trim, width drift, heading drift and token/spacing drift.

Phase 4 — Complete Surface Census

• Discover every meaningful reachable state from canonical navigation, including nested Community flow.
• Fail verification when a meaningful reachable destination has no canonical registry entry.
• Add capture/navigation definitions for every visually meaningful state that can be deterministically reached.
• Distinguish true ephemeral state from a meaningful surface so modals/transient overlays are not over-counted.

Phase 5 — Normalize surface families

Normalize one family at a time against the grammar:

1. Dashboard reference
2. Library + every Library child
3. Settings/Manage + every child
4. Community + every Community child
5. Story Map / Visual Story / Scene Timeline and production surfaces
6. remaining specialist/contextual surfaces

A family does not advance until its structural blockers are zero.

Phase 6 — Bounded repair mode

Add deterministic repair support to the existing UI Continuity Agent for only mechanical, unambiguous drift, such as:

• replacing local colours with Skin V1 tokens;
• replacing local padding with spacing tokens;
• using the canonical return/header component;
• normalizing standard border variables;
• applying canonical class shell/measure.

Ambiguous UX/layout decisions remain Human-approved proposals.

Acceptance criteria

1. There is one canonical Surface Registry; UI Continuity and WebMCP no longer own divergent screen lists.
2. Skin V1 has an explicit structural Surface Grammar independent of screenshot pixels.
3. Dashboard remains the canonical visual reference.
4. Every meaningful reachable surface is represented in the census, including nested Community flow.
5. A screen cannot pass Experience Skins verification with a return control on the wrong side, missing/extra standard frame, materially incorrect width, noncanonical structural trim, off-grid structural spacing, or undeclared local palette treatment unless an explicit class exception exists.
6. UI Continuity reports geometry/token evidence and surface-class comparison, not only broad shell/navigation state.
7. Screenshot baselines remain a secondary regression safety net.
8. No second verifier, agent, design system, story authority or navigation model is introduced.
9. Mechanical repair can eventually be automated only within deterministic bounded rules; ambiguous design remains Human-controlled.
10. Surface-family normalization can proceed screen-by-screen without reintroducing drift elsewhere.

Non-goals

• no unrelated Dashboard redesign;
• no new story/canon authority;
• no new navigation system;
• no second visual-verification stack;
• no requirement that every surface have identical content layout;
• no automatic Human baseline approval;
• no giant one-shot rewrite before the governing contract exists.

[BryanHarrisScripts]

Phase 1 Developer Brief — One Surface Registry consumed by verification

Why this phase comes first

Human review found that visual drift can recur because UI Continuity, WebMCP and Visual Director do not yet take their runtime surface inventory from one authority. Phase 0 created the canonical Skin V1 Surface Grammar and census. Phase 1 now changes ownership, not product behavior.

Conversation / decision audit carried forward

• Dashboard remains the sole canonical Skin V1 visual authority.
• Do not introduce a second verifier, design system, navigation model, story authority or baseline workflow.
• UI Continuity remains read-only in this phase; deterministic repair mode is later work.
• Existing routes/deep links must keep working.
• WebMCP remains the standard Human/UAT evidence path and must keep current capture/navigation behavior.
• Structural consistency must eventually become deterministic CI evidence rather than relying primarily on screenshot pixels.
• Nested Community, Library, Settings and later production states must not disappear from the census simply because they are not yet standard captures.
• Full builds/UAT stay in GitHub CI; local/focused checks should stay bounded to changed code.

Phase 1 implementation contract

1. Add one runtime loader/projection for config/skin-v1-surface-registry.json.
2. UI Continuity must derive the screens it inspects from canonical continuityIds; config/ui-continuity-agent-registry.json becomes compatibility metadata only.
3. WebMCP/Visual Director must derive the standard runtime target list from canonical webmcpId mappings; webmcp-surface-capture-registry.mjs remains detailed selector/navigation metadata, not inventory authority.
4. Fail closed if canonical mappings point to missing compatibility metadata or if compatibility inventories contain undeclared runtime entries.
5. Preserve the existing 26 standard WebMCP capture definitions and existing UI Continuity routes while changing who owns inclusion/order.
6. Add regression tests proving core runtime consumers use the canonical projection rather than independent lists.
7. No production UI, route, story/canon or baseline lock changes in this phase.

Exit criteria

• One canonical registry owns runtime inclusion/order for both UI Continuity and WebMCP/Visual Director.
• Duplicate inventories can no longer silently diverge.
• Existing capture/navigation behavior remains unchanged.
• Focused tests pass.
• Exact-head Architecture Verification is green before merge.