feat: redesign TanStack Devtools workbench

.changeset/tanstack-devtools-branding.md

@@ -0,0 +1,13 @@
+---
+'@tanstack/devtools': minor
+'@tanstack/devtools-ui': minor
+'@tanstack/devtools-a11y': minor
+---
+
+feat: apply TanStack branding and the compact Workbench layout across core, shared UI, and accessibility Devtools
+
+The Workbench now separates chrome from canvas: the header and the secondary strips paint the brand surface and share one 16px gutter with the content below them. The palm emblem is inline SVG instead of a filtered raster, plugin destinations get a real empty state, and the Marketplace, SEO, and Settings destinations drop their competing accent colours in favour of the semantic theme.
+
+The secondary strip gets a pull tab on its bottom edge that folds the strip away behind the header, leaving the panel height and the destination content untouched. It only appears on destinations that have a strip.
+
+Fixes along the way: the resize handle had grown to 24px and sat on top of the header, so a press aimed at a header button started a resize instead of clicking; the Marketplace settings drawer was `position: fixed` and covered the host page instead of the Workbench; the floating trigger lost its brand fill on hover and its transition was overridden away; the "New" ribbon on a plugin card overlapped the card icon; scroll gestures inside the panel chained on to the host page; and the hotkey editor showed each shortcut's description as its heading and never rendered its title.

docs/architecture.md

@@ -14,7 +14,7 @@ block-beta
     end
     block:core["Core Layer"]
         columns 3
-        Shell["Devtools Shell"] UI["UI Components"] Client["Event Client"]
+        Workbench["Devtools Workbench"] UI["UI components + private semantic theme"] Client["Event Client"]
     end
     block:transport["Transport Layer"]
         columns 3
@@ -37,10 +37,10 @@ graph TD
     end
 
     subgraph Core["Core Layer"]
-        shell["@tanstack/devtools<br/><i>Core shell (Solid.js)</i>"]
+        shell["@tanstack/devtools<br/><i>Core Workbench (Solid.js)</i>"]
         client["@tanstack/devtools-client<br/><i>Core devtools events</i>"]
         eventClient["@tanstack/devtools-event-client<br/><i>Generic EventClient</i>"]
-        ui["@tanstack/devtools-ui<br/><i>Shared UI components</i>"]
+        ui["@tanstack/devtools-ui<br/><i>Shared UI + private semantic-theme owner</i>"]
         clientBus["@tanstack/devtools-event-bus/client<br/><i>ClientEventBus</i>"]
     end
 
@@ -147,17 +147,32 @@ The devtools shell is a Solid.js application that renders the entire devtools UI
 
 The shell renders:
 - A **trigger button** (the floating devtools toggle, customizable or replaceable)
-- A **resizable panel** (docked to the bottom of the viewport, resizable via drag)
-- **Tab navigation** for switching between plugins, settings, SEO inspector, and the plugin marketplace
+- A **resizable Workbench panel** (docked to the top or bottom of the viewport, resizable via pointer or keyboard)
+- A compact **36px TanStack Devtools header** with Plugins, Marketplace, SEO, and Settings destinations. The palm emblem is inline SVG, so it stays sharp and takes its colour from the theme.
+- A fixed-height **44px secondary strip** for plugin and SEO navigation. It scrolls horizontally when space is limited, and a pull tab on its bottom edge folds it away behind the header. Folding changes nothing else — the panel keeps its height and the destination content keeps running — so the tab is rendered only on the destinations that have a strip.
+- A separate **Marketplace** header tab that does not disturb mounted plugin panes
 - A **settings panel** for theme, hotkeys, position, and other preferences
-- **Plugin containers** -- DOM elements where each plugin's UI is mounted
+- Up to three simultaneous **plugin mount frames**, divided into equal widths by static separators
 
 Settings and UI state (panel size, position, active tab, theme) are persisted in `localStorage` so they survive page reloads.
 
+The core shell owns the Workbench header, navigation, mount-frame geometry, separators, and surrounding light/dark surfaces. Each external plugin owns everything inside its mount target; core styling deliberately does not reach into plugin descendants. Detaching the Workbench uses a fixed `100vh` Picture-in-Picture layout and restores the stored docked height when reattached.
+
+#### Workbench surfaces and gutters
+
+Two rules keep the shell reading as one surface:
+
+- **Chrome versus canvas.** The header and every secondary strip paint the brand surface (cream in light mode, near-black in dark mode) and close with a translucent ink hairline. Destination content and plugin mount frames paint the workspace surface. A plugin pane can paint any colour it likes, so the separator between panes uses a mid-tone border that stays visible against both.
+- **One gutter.** `WORKBENCH_GUTTER` (16px, or `WORKBENCH_GUTTER_NARROW` at 12px below 430px) is the single inline gutter. The header, the strips, and each destination's content all start there, so the left edge is one column instead of three. `MainPanel withPadding` uses the same value.
+
+Colour comes from the semantic theme only. Raw hex values in core-owned source are rejected by `tests/semantic-color-usage.test.ts` unless they carry a narrow, path-scoped `semantic-color-exempt` marker — currently only third-party network marks and the source-inspector highlight alpha. Status colours (success, warning, error, info) mark real state; identity accents do not compete with them, so a card that is both featured and active keeps the neutral outline and lets its badge say which it is.
+
 ### @tanstack/devtools-ui -- Component Library
 
 A shared Solid.js component library used by the core shell and available for use in Solid.js plugins. Provides buttons, inputs, checkboxes, a JSON tree viewer, section layouts, and other UI primitives. The `@tanstack/devtools-utils` package also depends on it to provide framework-specific plugin helpers.
 
+Core packages share a private semantic resolver through `@tanstack/devtools-ui/internal`. It supplies TanStack light/dark colors, typography, spacing, status roles, and focus treatment to core-owned UI and the accessibility plugin. This internal subpath is an implementation boundary, not a public theming API for application plugins.
+
 ### @tanstack/devtools-client -- Core Event Client
 
 A specialized `EventClient` pre-configured with `pluginId: 'tanstack-devtools-core'` and a fixed event map for devtools-internal operations:

docs/overview.md

@@ -83,12 +83,15 @@ Your application loads a **Framework Adapter**, which mounts the **Core Shell**.
 
 ## Key Features
 
+- **Compact TanStack Workbench**: The trigger reveals a branded light/dark panel with a 36px banner and Plugins, Marketplace, SEO, and Settings navigation. Navigation and the strips sit on the cream (or near-black) chrome band, content sits on the workspace surface, and every surface shares one 16px gutter. The whole panel keeps its existing hide-and-reveal lifecycle.
 - **Framework Agnostic**: Works with React, Vue, Solid, and Preact out of the box.
-- **Plugin System & Marketplace**: Build, share, and install devtools plugins with a simple API.
+- **Plugin System & Marketplace**: Build, share, discover, and install devtools plugins with a simple API. The fixed 44px secondary strip scrolls horizontally when space is limited. Marketplace is a separate header tab.
+- **Simultaneous Plugin Panes**: Open up to three plugins at once in equal-width panes while each plugin retains ownership of its own UI.
+- **Accessibility Auditing**: Add the accessibility plugin during development to surface issues alongside the other plugin panes; the basic React example includes an intentional audit fixture.
 - **Type-Safe Event System**: Communicate between plugins and the shell using fully typed events.
 - **Source Inspector**: Click any element in your app to jump straight to its source code (go-to-source).
 - **Console Piping**: Route devtools output to your browser console for a familiar debugging workflow.
-- **Picture-in-Picture Mode**: Pop the devtools panel out into its own window so it never covers your app.
+- **Picture-in-Picture Mode**: Pop the Workbench into a fixed-`100vh` window; reattaching restores its stored docked height.
 - **Customizable Hotkeys**: Rebind keyboard shortcuts to match your workflow.
 
 ## Next Steps