The engine's default reveal chrome vanishes on a dark ground

Sub-issue of #13158 (dock layouts). Seen on 2026-09-02 while reading #18074's reveal motion on the served dock-popout fixture in the neo-dark theme; filed on the operator's word so it does not get lost.

Context

A revealed auto-hidden pane is an overlay over the workspace. The engine paints it from four theme-agnostic tokens (resources/scss/src/dashboard/Container.scss:128-133): --dock-reveal-background: var(--neo-background-color, #fff), --dock-reveal-border: 0, --dock-reveal-radius: 0, --dock-reveal-shadow: 0 12px 32px rgb(0 0 0 / 28%). The comment above them says why: "A reveal is an overlay, so opacity and elevation are functional rather than decorative" — the shadow IS the edge.

The Problem

On a dark ground the shadow is not an edge. In neo-dark the overlay's background resolves to the same surface color as the pane beneath it (--neo-background-color → --sem-color-bg-neutral-default), the border is 0, and a 28%-black shadow on a near-black ground is invisible — the revealed pane reads as the pane it covers, with a title line floating in it. Read on the fixture: the settled overlay over Pinned is indistinguishable from Pinned except for its header text.

Both flagship hosts already override the tokens because of this: apps/workstation (resources/scss/src/apps/workstation/Workspace.scss:98-104 — its rail surface, a 1px signal-mixed border, an 8px radius, a 72%-ground shadow plus a signal glow; measured live: background rgb(14 19 26) beside a cell at rgb(20 26 35), border 1px solid teal) and the Fleet cockpit (neo-agent-institution fleet/cockpit/Container.scss:182-185 — --fm-rail background, 1px solid var(--fm-line) border). Every other consumer — the dock example, the component fixtures, a new adopter, a client workspace that has not written those lines — gets the invisible default. The engine's job is a discoverable overlay by default; aesthetics are the consumer's (the splitter-affordance floor in the same file states the same principle, :22-31).

The Architectural Reality

• The reveal tokens are declared once on .neo-dashboard in Container.scss and are theme-agnostic; no theme file sets them (grep -rn dock-reveal resources/scss finds only the two app overrides). The neo themes' surface vocabulary lives in theme-neo-dark/Global.scss / theme-neo-light/Global.scss (--neo-background-color, the --sem-color-* set).
• The splitter floor (:22-31) shows the house pattern for a discoverability floor: values resolve through currentColor so the engine needs no knowledge of the host palette; a color-mix band reads on any ground.
• #14779 owns motion; this is paint. #18070 (landed as PR #18073) owns where the overlay starts; this is what its edge looks like once it is there.

The Fix

A discoverability floor for the reveal's edge that reads on any ground, in the engine defaults — the same currentColor pattern as the splitter floor:

1. --dock-reveal-border: 1px solid color-mix(in srgb, currentColor 22%, transparent) — a hairline that separates the overlay from an identical surface beneath it, light or dark, without naming a color.
2. --dock-reveal-shadow: keep the elevation, make it read on dark: a two-layer shadow — the existing soft drop plus a wide low-alpha currentColor halo (0 0 0 1px color-mix(in srgb, currentColor 8%, transparent) or a color-mix glow) so elevation survives a black ground.
3. No radius change (consumers set it), no background change (the surface stays the host's).
4. A paint witness in the component tier (the DockRailTabPaint pattern: measured computed values on the mounted overlay in BOTH neo themes): the overlay's computed border is not 0px none and its box-shadow is not none; plus a luminance-delta read at the overlay's edge against the pane beneath, honest in either skin (the AgentCard witness's contrast guard is the precedent).
5. The two app overrides stay as they are (they are stronger than the floor and win on specificity).

Contract Ledger Matrix

Decision Record impact: none (ADR 0029 §2.7 describes the reveal as an overlay; paint is a theme floor).

Acceptance Criteria

• On the dock-popout fixture in neo-dark AND neo-light, the mounted overlay's computed border is a visible hairline and its box-shadow is not none; a luminance delta at the overlay's edge against the pane beneath exceeds a stated floor in both skins. Red on dev in neo-dark (border 0px, delta ≈ 0).
• apps/workstation and the dock example render byte-identically where they override; where they do not, the floor shows (screenshots, design-read).
• check-scss/lint green; no consumer SCSS change needed.

Out of Scope

• The reveal's motion (#18074 / PR #18079), its start geometry (#18070), its radius and surface color (consumer decisions).

Related

Parent: #13158. Siblings: #18074, #18070, #18067, #18071. Precedents: the splitter-affordance floor (Container.scss:22-31), DockRailTabPaint.spec.mjs (measured paint in both themes).

Live latest-open sweep: checked the latest 20 open issues at 2026-09-02T12:21Z — none on reveal paint or contrast (#18070 geometry, #18074 motion, #18071 tooltips); A2A claims of the last hour: none on this scope; the local ticket corpus on dock-reveal-shadow|dock-reveal-border returns nothing; ask_knowledge_base timed out twice on this query (recorded as such).

Origin Session ID: 91f83b9c-df95-4f72-a68f-d33f470792ac

Retrieval Hint: "dock reveal overlay default border shadow dark theme currentColor floor discoverability"

📜 Clio