DockLayouts styling now spans an engine affordance floor, registered theme identities, dock preview sheets, inline tab headers, action rails, splitters, rails, and Workstation-specific token values. Recent fixes repeatedly showed that correct component ownership does not guarantee correct CSS cascade authority.
The Problem
The Adoption guide says “skin it with tokens,” but does not teach the full layering model or how to verify it. Consumers can accidentally copy engine paint, lose popup-vessel token reach, create equal-specificity property conflicts, or make focus/overflow action chrome visually unstable.
The Architectural Reality
resources/scss/src/dashboard/** owns structural paint and neutral --dock-* consumption. Theme trees provide registered defaults/accents. App sheets such as Workstation set values and deliberate density policy. Tab-header/action chrome crosses shared tab/toolbar primitives while floating overflow menus and popup vessels have separate embodiment scopes.
The Fix
Create learn/guides/uibuildingblocks/DockLayoutsStyling.md: a visual-language guide explaining engine floor versus theme versus app skin, token reach across vessels, inline header/action composition, and computed-style verification.
Contract Ledger
Target Surface
Source of Authority
Proposed Behavior
Fallback
Docs
Evidence
Styling guide
Current SCSS structural/theme/app layers
Teach ownership and token flow without copying declaration catalogs
Re-census at pickup
New guide
Computed-style + screenshot receipts
Floating embodiments
Current overflow/popup/reveal implementations
Explain token reach across body/window scopes
Name honest limits
Same guide
Workstation + standalone consumers
Registration
Existing guide siblings
One discoverable UI-building-blocks guide
No generated-output edits
tree + SEO inputs
lint + rendered portal
Decision Record impact
aligned-with ADR 0029
Decision Record
Not needed; this guide explains presentation layering.
Acceptance Criteria
The guide clears the full guide-authoring bar: source/tool-grounded narrative, reader-owned benefits, lived maintainer voice, and at least one render-verified flowchart TD.
The guide separates explanation from reference: no inlined API/schema/test catalog, and no ticket or PR ids in guide prose.
The new source guide is registered in learn/tree.json and the SEO PRIORITIES input; generated sitemap/LLM outputs remain untouched.
Current-source consistency, guide lint, tree lint, portal rendering, and an independent cross-family whole-guide review are recorded in the PR.
The guide distinguishes engine structural paint, registered theme values, and app-owned token values/density deviations.
Inline tab headers, overflow-first/close-last action chrome, rails, splitters, previews, reveal controls, menus, and popup vessels are grounded in current rendered consumers.
Computed-style and screenshot receipts cover every registered Engine theme relevant at authoring time plus Workstation palettes; no hard-coded theme count.
Specificity and inheritance are explained through one real failure-and-fix story, not a selector catalog.
Out of Scope
Redesigning the visual language, relocating SCSS, or duplicating the generic Styling and Theming guide.
Avoided Traps
Do not move app identity into engine defaults, treat selector presence as paint ownership, hand-edit generated CSS, or infer cascade correctness from SCSS source alone.
Activation Gate
Do not author the guide while #17836 remains an active refactoring authority. At pickup, re-run Memory Core mining, read the current ADR 0029 and source/test surfaces named below, exercise the relevant live subsystem, and revalidate the proposed guide boundary. If the final API makes this split wrong, reshape this ticket before writing—do not preserve a stale outline.
Related
Related: parent guide Epic #17540; blocked by active DockLayouts refactor Epic #17836; authority ADR 0029.
Retrieval Hint: query_raw_memories("DockLayouts guide series post-refactor final API")
Creation freshness: live created-descending sweep of the latest 20 open Engine issues at 2026-09-01T17:49:38Z found no equivalent guide ticket; the all-state latest-30 A2A sweep found no overlapping guide claim. The Knowledge Base returned stale pre-cut names, so live source, ADR 0029, and the current guide tree remain authority.
Context
DockLayouts styling now spans an engine affordance floor, registered theme identities, dock preview sheets, inline tab headers, action rails, splitters, rails, and Workstation-specific token values. Recent fixes repeatedly showed that correct component ownership does not guarantee correct CSS cascade authority.
The Problem
The Adoption guide says “skin it with tokens,” but does not teach the full layering model or how to verify it. Consumers can accidentally copy engine paint, lose popup-vessel token reach, create equal-specificity property conflicts, or make focus/overflow action chrome visually unstable.
The Architectural Reality
resources/scss/src/dashboard/**owns structural paint and neutral--dock-*consumption. Theme trees provide registered defaults/accents. App sheets such as Workstation set values and deliberate density policy. Tab-header/action chrome crosses shared tab/toolbar primitives while floating overflow menus and popup vessels have separate embodiment scopes.The Fix
Create
learn/guides/uibuildingblocks/DockLayoutsStyling.md: a visual-language guide explaining engine floor versus theme versus app skin, token reach across vessels, inline header/action composition, and computed-style verification.Contract Ledger
Decision Record impact
aligned-with ADR 0029
Decision Record
Not needed; this guide explains presentation layering.
Acceptance Criteria
flowchart TD.learn/tree.jsonand the SEOPRIORITIESinput; generated sitemap/LLM outputs remain untouched.Out of Scope
Redesigning the visual language, relocating SCSS, or duplicating the generic Styling and Theming guide.
Avoided Traps
Do not move app identity into engine defaults, treat selector presence as paint ownership, hand-edit generated CSS, or infer cascade correctness from SCSS source alone.
Activation Gate
Do not author the guide while #17836 remains an active refactoring authority. At pickup, re-run Memory Core mining, read the current ADR 0029 and source/test surfaces named below, exercise the relevant live subsystem, and revalidate the proposed guide boundary. If the final API makes this split wrong, reshape this ticket before writing—do not preserve a stale outline.
Related
Related: parent guide Epic #17540; blocked by active DockLayouts refactor Epic #17836; authority ADR 0029.
Origin Session ID: 309a78d7-2d95-4f23-bdfc-69d2ae393a5d
Retrieval Hint:
query_raw_memories("DockLayouts guide series post-refactor final API")Creation freshness: live created-descending sweep of the latest 20 open Engine issues at 2026-09-01T17:49:38Z found no equivalent guide ticket; the all-state latest-30 A2A sweep found no overlapping guide claim. The Knowledge Base returned stale pre-cut names, so live source, ADR 0029, and the current guide tree remain authority.