From d87d40a4ccfbde4ca2aca3d6624e1a7427c76f94 Mon Sep 17 00:00:00 2001
From: Marek Martuszewski <marek@fachowo.co>
Date: Thu, 20 Aug 2026 14:43:41 +0200
Subject: [PATCH] style(runner): unify the editor shell and panels on the
 design's type/grid scales
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A design-alignment pass over the authoring shell and both drawers, built
against Figma 48:6560 (light) / 31:6438 (dark) and the docs assistant:

- Typography: one scale in theme.type (base 12/20, small 10/20, row 12/16,
  label 10/20+tracking) replacing ~50 ad-hoc sizes; sidebar rows raised to
  12px by decision, category labels stay 10.
- Spacing: 4px grid discipline (8px rhythm) across shell and app pages;
  geometry-locked exceptions documented inline.
- Editor: Fira Code 12/20 (bundled via @fontsource), 16px inset, chromeless
  gutter, editorBg token over githubDark's #0d1117 (Prec.high — the theme
  prop outranks plain extensions); Mod-F search panel restyled to shell idiom.
- Drawers: full-height, slide-in from the right, docs-assistant chrome;
  Ask AI transcript/composer restyled after the Docs assistant; Style panel
  aligned on the 24px inset with Theme Builder's row layout (label + info
  tooltip left, control right), floating pickers with Common/Pick-color tabs,
  muted-track segmented controllers, framed menu lists shared with the chat
  suggestions, dismissible intro notice, and the AI tab on the chat composer.
- Classes over inline styles: Drawer registers its stylesheet via installCss;
  the panels' rules live in panels.css with tokens as CSS variables
  (--hot-font-* added); the ADR-0026 hover-vs-inline trap disappears with it.
- Tooltips for the two toolbar CTAs share one treatment; thin scrollbars
  shell-wide; theme toggle moved between Download and the avatar; lighter
  hover token in light mode (0.16 -> 0.10).

E2E updated where intent changed: full-height drawers cover the top-bar
triggers (switching is keyboard-reachable, tests activate via Enter), the
composer is transparent over the drawer surface, the edit box and token rows
are located by class/data-token instead of inline-style sniffing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 runner/apps/authoring/index.html              |  18 +
 runner/apps/authoring/package.json            |   1 +
 runner/apps/authoring/src/Admin.tsx           |  58 +--
 runner/apps/authoring/src/Chat.tsx            | 167 +++-----
 runner/apps/authoring/src/DocsCascader.tsx    |   6 +-
 runner/apps/authoring/src/Guide.tsx           |   8 +-
 runner/apps/authoring/src/MarkdownField.tsx   |   6 +-
 runner/apps/authoring/src/MyDemos.tsx         |   2 +-
 runner/apps/authoring/src/StylePanel.tsx      | 340 ++++++++-------
 runner/apps/authoring/src/main.tsx            |   8 +
 runner/apps/authoring/src/markdown.tsx        |  18 +-
 runner/apps/authoring/src/panels.css          | 396 ++++++++++++++++++
 runner/apps/authoring/src/theme/controls.tsx  | 224 ++++++----
 runner/e2e/panels.spec.ts                     |  27 +-
 runner/e2e/style-panel.spec.ts                |  11 +-
 .../packages/editor-shell/src/AccountMenu.tsx |   2 +-
 runner/packages/editor-shell/src/BoxInfo.tsx  |  16 +-
 .../packages/editor-shell/src/CodeEditor.tsx  |  90 +++-
 .../editor-shell/src/Dependencies.tsx         |   8 +-
 runner/packages/editor-shell/src/Drawer.tsx   | 157 ++++---
 .../packages/editor-shell/src/EditorTabs.tsx  |   6 +-
 runner/packages/editor-shell/src/FileTree.tsx |  18 +-
 .../packages/editor-shell/src/PreviewBar.tsx  |  15 +-
 .../packages/editor-shell/src/PreviewPane.tsx |  10 +-
 runner/packages/editor-shell/src/SideNav.tsx  |   8 +-
 runner/packages/editor-shell/src/TopBar.tsx   |   9 +-
 runner/packages/editor-shell/src/icons/ui.tsx |   8 +
 runner/packages/editor-shell/src/styles.ts    |  22 +-
 runner/packages/editor-shell/src/theme.ts     |  49 ++-
 runner/pnpm-lock.yaml                         |   8 +
 30 files changed, 1172 insertions(+), 544 deletions(-)
 create mode 100644 runner/apps/authoring/src/panels.css

diff --git a/runner/apps/authoring/index.html b/runner/apps/authoring/index.html
index 871c95ffc..3d1a65a5c 100644
--- a/runner/apps/authoring/index.html
+++ b/runner/apps/authoring/index.html
@@ -232,6 +232,24 @@
         outline: 2px solid var(--hot-color-accent);
         outline-offset: 1px;
       }
+      /* The Ask AI panel's rules (bubble tail, suggestion arrows, composer states)
+         live in src/panels.css, imported from main.tsx — this block keeps only what
+         must exist pre-React or is shared across panels. */
+      /* Thin scrollbars, shell-wide. `scrollbar-color` is inherited, so the root
+         declaration reaches every scroller — sidebar, drawers, CodeMirror — but
+         `scrollbar-width` is *not* (measured: a nested scroller computes `auto`),
+         hence the universal selector. Zero specificity, so `.hot-tab-strip`'s `none`
+         below still wins. The ::-webkit-* pseudos are for Safari only: Chrome
+         disables them the moment the standard properties are set, and Firefox never
+         reads them. Track mirrors the surface, thumb the border, so the bar sits in
+         the chrome instead of on top of it. Before React emits the custom properties
+         the var()s are unset and the UA default paints — one frame, unstyled, not
+         broken. */
+      * { scrollbar-width: thin; }
+      html { scrollbar-color: var(--hot-color-border) var(--hot-color-surface); }
+      ::-webkit-scrollbar { width: 8px; height: 8px; }
+      ::-webkit-scrollbar-track { background: var(--hot-color-surface); }
+      ::-webkit-scrollbar-thumb { background: var(--hot-color-border); border-radius: 4px; }
       /* The strip scrolls when the open files outgrow it. Both properties: the WebKit
          pseudo-element alone still leaves a scrollbar in Firefox, and a 36px bar has
          no room for one — it would sit on the strip's inset hairline. */
diff --git a/runner/apps/authoring/package.json b/runner/apps/authoring/package.json
index 084980df6..dbed4293f 100644
--- a/runner/apps/authoring/package.json
+++ b/runner/apps/authoring/package.json
@@ -10,6 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@fontsource/fira-code": "^5.3.0",
     "@handsontable/demo-editor-shell": "workspace:*",
     "@handsontable/demo-runtime": "workspace:*",
     "@sentry/react": "^10.68.0",
diff --git a/runner/apps/authoring/src/Admin.tsx b/runner/apps/authoring/src/Admin.tsx
index 64243e699..f3bd90722 100644
--- a/runner/apps/authoring/src/Admin.tsx
+++ b/runner/apps/authoring/src/Admin.tsx
@@ -297,7 +297,7 @@ export function AdminPanel({ apiBase, token }: AdminPanelProps) {
               const rows = dailyMetric(report.usage, metric);
               if (!rows.length) return null;
               return (
-                <div key={metric} style={{ marginBottom: 18 }}>
+                <div key={metric} style={{ marginBottom: 16 }}>
                   <div style={subhead}>{METRIC_LABEL[metric] ?? metric}</div>
                   <Bars rows={rows} format={int} emptyText="" />
                 </div>
@@ -444,8 +444,8 @@ function SettingsForm({
   }, [settings]);
 
   const field = (key: keyof BudgetSettings, label: string, hint: string) => (
-    <label style={{ display: "block", marginBottom: 10 }}>
-      <div style={{ fontSize: 12, marginBottom: 3 }}>{label}</div>
+    <label style={{ display: "block", marginBottom: 8 }}>
+      <div style={{ fontSize: 12, marginBottom: 4 }}>{label}</div>
       <input
         type="number"
         min={0}
@@ -454,7 +454,7 @@ function SettingsForm({
         onChange={(e) => setDraft({ ...draft, [key]: Number(e.target.value) })}
         style={input}
       />
-      <div style={{ fontSize: 11, color: theme.color.textMuted, marginTop: 2 }}>{hint}</div>
+      <div style={{ fontSize: 11, color: theme.color.textMuted, marginTop: 4 }}>{hint}</div>
     </label>
   );
 
@@ -494,7 +494,7 @@ function SettingsForm({
   const pctOf = (v: number) => (draft.limitUsd > 0 ? `${Math.round((v / draft.limitUsd) * 100)}% of the ceiling` : "");
 
   return (
-    <section style={{ marginTop: 18 }}>
+    <section style={{ marginTop: 16 }}>
       <button type="button" style={chip} onClick={() => setOpen((v) => !v)} aria-expanded={open}>
         {open ? "▾" : "▸"} Guardrail settings
         <span style={{ color: theme.color.textMuted, marginLeft: 8 }}>
@@ -505,7 +505,7 @@ function SettingsForm({
       </button>
 
       {open && (
-        <div style={{ ...card, background: theme.color.surface, borderLeftWidth: 1, marginTop: 10 }}>
+        <div style={{ ...card, background: theme.color.surface, borderLeftWidth: 1, marginTop: 8 }}>
           <div style={{ display: "flex", gap: 24, flexWrap: "wrap" }}>
             <div style={{ minWidth: 200, flex: "1 1 200px" }}>
               {field("limitUsd", "Monthly ceiling ($)", "The number everything else is measured against.")}
@@ -517,8 +517,8 @@ function SettingsForm({
             </div>
             <div style={{ minWidth: 200, flex: "1 1 200px" }}>
               {field("closedUsd", "Close live editing ($)", `${pctOf(draft.closedUsd)} — running sessions torn down.`)}
-              <label style={{ display: "block", marginBottom: 10 }}>
-                <div style={{ fontSize: 12, marginBottom: 3 }}>Alert thresholds ($)</div>
+              <label style={{ display: "block", marginBottom: 8 }}>
+                <div style={{ fontSize: 12, marginBottom: 4 }}>Alert thresholds ($)</div>
                 <input
                   type="text"
                   value={alertsText}
@@ -526,7 +526,7 @@ function SettingsForm({
                   placeholder="200, 500, 800"
                   style={input}
                 />
-                <div style={{ fontSize: 11, color: theme.color.textMuted, marginTop: 2 }}>
+                <div style={{ fontSize: 11, color: theme.color.textMuted, marginTop: 4 }}>
                   Notify once per month per threshold, on this runner’s own spend.
                 </div>
               </label>
@@ -634,7 +634,7 @@ function AssistantSection({ report }: { report: UsageReport }) {
         <Stat label="Failures" value={int(errors)} hint="Gateway unavailable or misconfigured" />
       </section>
 
-      <div style={{ display: "flex", gap: 32, flexWrap: "wrap", marginTop: 18 }}>
+      <div style={{ display: "flex", gap: 32, flexWrap: "wrap", marginTop: 16 }}>
         <div style={{ minWidth: 280, flex: "1 1 280px" }}>
           <div style={subhead}>Questions per day</div>
           <Bars rows={dailyMetric(usage, "chat_message")} format={int} emptyText="—" />
@@ -645,7 +645,7 @@ function AssistantSection({ report }: { report: UsageReport }) {
         </div>
       </div>
 
-      <div style={{ display: "flex", gap: 32, flexWrap: "wrap", marginTop: 18 }}>
+      <div style={{ display: "flex", gap: 32, flexWrap: "wrap", marginTop: 16 }}>
         <div style={{ minWidth: 240, flex: "1 1 240px" }}>
           <div style={subhead}>Frameworks asked about</div>
           <Bars rows={byDimension(usage, "chat_message")} format={int} emptyText="—" />
@@ -705,12 +705,12 @@ function AudienceSection({ audience, days }: { audience: Audience; days: number
         </div>
       </div>
 
-      <div style={{ display: "flex", gap: 32, flexWrap: "wrap", marginTop: 18 }}>
+      <div style={{ display: "flex", gap: 32, flexWrap: "wrap", marginTop: 16 }}>
         <TopList title="Pages" rows={audience.pages} />
         <TopList title="Demos" rows={audience.demos} />
         <TopList title="Referrers" rows={audience.referrers} />
       </div>
-      <div style={{ display: "flex", gap: 32, flexWrap: "wrap", marginTop: 18 }}>
+      <div style={{ display: "flex", gap: 32, flexWrap: "wrap", marginTop: 16 }}>
         <TopList title="Countries" rows={audience.countries} upper />
         <TopList title="Devices" rows={audience.devices} />
         <TopList title="Browsers" rows={audience.browsers} />
@@ -839,7 +839,7 @@ function LiveSessionsSection({
 
   return (
     <Section title="Live sessions">
-      <div style={{ display: "flex", alignItems: "center", gap: 12, flexWrap: "wrap", marginBottom: 10 }}>
+      <div style={{ display: "flex", alignItems: "center", gap: 12, flexWrap: "wrap", marginBottom: 8 }}>
         <label style={{ display: "flex", alignItems: "center", gap: 6, fontSize: 13 }}>
           <input
             type="checkbox"
@@ -925,7 +925,7 @@ function LiveSessionsSection({
       )}
 
       {page.total > page.limit && (
-        <div style={{ display: "flex", alignItems: "center", gap: 8, marginTop: 10 }}>
+        <div style={{ display: "flex", alignItems: "center", gap: 8, marginTop: 8 }}>
           <button
             type="button"
             style={chip}
@@ -1108,53 +1108,53 @@ const page: React.CSSProperties = {
   minHeight: "100%", padding: "20px 24px 60px", maxWidth: 1100, margin: "0 auto",
 };
 const head: React.CSSProperties = {
-  display: "flex", alignItems: "center", gap: 10, paddingBottom: 14,
+  display: "flex", alignItems: "center", gap: 8, paddingBottom: 16,
   borderBottom: `1px solid ${theme.color.border}`, flexWrap: "wrap",
 };
 const h1: React.CSSProperties = { fontSize: 17, margin: 0, fontWeight: 600 };
-const h2: React.CSSProperties = { fontSize: 14, margin: "0 0 10px", fontWeight: 600 };
-const subhead: React.CSSProperties = { fontSize: 12, color: theme.color.textMuted, margin: "0 0 6px" };
+const h2: React.CSSProperties = { fontSize: 14, margin: "0 0 8px", fontWeight: 600 };
+const subhead: React.CSSProperties = { fontSize: 12, color: theme.color.textMuted, margin: "0 0 8px" };
 const chip: React.CSSProperties = {
   fontFamily: theme.font.ui, fontSize: 12, color: theme.color.text, background: theme.color.surfaceRaised,
-  border: `1px solid ${theme.color.border}`, borderRadius: 6, padding: "4px 9px", cursor: "pointer",
+  border: `1px solid ${theme.color.border}`, borderRadius: 6, padding: "4px 8px", cursor: "pointer",
 };
 const chipActive: React.CSSProperties = {
   background: theme.color.accent, color: theme.color.accentContrast, borderColor: theme.color.accent,
 };
 const card: React.CSSProperties = {
-  marginTop: 18, padding: 16, border: `1px solid ${theme.color.border}`,
+  marginTop: 16, padding: 16, border: `1px solid ${theme.color.border}`,
   borderLeftWidth: 4, borderRadius: theme.radius.md, background: theme.color.surfaceMuted,
 };
 const pill: React.CSSProperties = {
-  color: theme.color.accentContrast, borderRadius: 999, padding: "2px 9px", fontSize: 11.5, fontWeight: 600,
+  color: theme.color.accentContrast, borderRadius: 999, padding: "2px 8px", fontSize: 11.5, fontWeight: 600,
 };
 const meter: React.CSSProperties = {
   position: "relative", height: 10, borderRadius: 999, background: theme.color.surfaceMuted,
-  border: `1px solid ${theme.color.border}`, margin: "14px 0 10px", overflow: "hidden",
+  border: `1px solid ${theme.color.border}`, margin: "16px 0 8px", overflow: "hidden",
 };
 const meterFill: React.CSSProperties = { position: "absolute", inset: 0, borderRadius: 999 };
 const meterMark: React.CSSProperties = {
   position: "absolute", top: 0, bottom: 0, width: 1, background: theme.color.textMuted, opacity: 0.6,
 };
 const grid: React.CSSProperties = {
-  display: "grid", gap: 10, marginTop: 16,
+  display: "grid", gap: 8, marginTop: 16,
   gridTemplateColumns: "repeat(auto-fit, minmax(170px, 1fr))",
 };
 const statCard: React.CSSProperties = {
-  border: `1px solid ${theme.color.border}`, borderRadius: theme.radius.md, padding: "10px 12px",
+  border: `1px solid ${theme.color.border}`, borderRadius: theme.radius.md, padding: "8px 12px",
 };
 const input: React.CSSProperties = {
   width: "100%", boxSizing: "border-box", fontFamily: theme.font.ui, fontSize: 13,
-  padding: "5px 8px", border: `1px solid ${theme.color.border}`, borderRadius: 6, color: theme.color.text,
+  padding: "4px 8px", border: `1px solid ${theme.color.border}`, borderRadius: 6, color: theme.color.text,
 };
 const table: React.CSSProperties = { width: "100%", borderCollapse: "collapse", fontSize: 13 };
 const th: React.CSSProperties = {
   fontSize: 11.5, textTransform: "uppercase", letterSpacing: 0.4, color: theme.color.textMuted,
-  fontWeight: 600, padding: "6px 8px", borderBottom: `1px solid ${theme.color.border}`,
+  fontWeight: 600, padding: "4px 8px", borderBottom: `1px solid ${theme.color.border}`,
 };
-const td: React.CSSProperties = { padding: "6px 8px", borderBottom: `1px solid ${theme.color.surfaceMuted}` };
-const note: React.CSSProperties = { fontSize: 12, color: theme.color.textMuted, margin: "10px 0 0", maxWidth: 720 };
-const barRow: React.CSSProperties = { display: "flex", alignItems: "center", gap: 8, padding: "2px 0" };
+const td: React.CSSProperties = { padding: "4px 8px", borderBottom: `1px solid ${theme.color.surfaceMuted}` };
+const note: React.CSSProperties = { fontSize: 12, color: theme.color.textMuted, margin: "8px 0 0", maxWidth: 720 };
+const barRow: React.CSSProperties = { display: "flex", alignItems: "center", gap: 8, padding: "4px 0" };
 const barLabel: React.CSSProperties = {
   width: 96, flex: "0 0 96px", fontSize: 11.5, color: theme.color.textMuted, fontFamily: theme.font.mono,
 };
diff --git a/runner/apps/authoring/src/Chat.tsx b/runner/apps/authoring/src/Chat.tsx
index 95992d497..b69bff4b4 100644
--- a/runner/apps/authoring/src/Chat.tsx
+++ b/runner/apps/authoring/src/Chat.tsx
@@ -10,7 +10,7 @@
 // feature, it is a data-loss bug with good intentions.
 
 import { useEffect, useRef, useState } from "react";
-import { Drawer, IconSparkles, theme } from "@handsontable/demo-editor-shell";
+import { Drawer, IconArrowUp, IconSparkles, theme } from "@handsontable/demo-editor-shell";
 import type { FilesMap } from "@handsontable/demo-runtime";
 import { searchDocs } from "./docsSearch.js";
 import { Markdown } from "./markdown.js";
@@ -215,57 +215,73 @@ export function ChatPanel({
     reportChatEvent(apiBase, "edit_undone", framework);
   }
 
-  /** The composer, pinned under the scrolling transcript by `Drawer`. */
+  /** The composer, pinned under the scrolling transcript by `Drawer`. Full-bleed
+   *  on the panel surface with the send arrow floated inside the field — the docs
+   *  assistant's composer (`.da-input` / `.da-send`), not a padded form row. */
   const footer = (
     <>
       <form
-        style={composer}
+        className="hot-chat-composer"
         onSubmit={(e) => { e.preventDefault(); void send(input); }}
       >
         <textarea
-          style={textarea}
+          className="hot-chat-input"
           value={input}
           onChange={(e) => setInput(e.target.value)}
           onKeyDown={(e) => {
             if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); void send(input); }
           }}
-          placeholder="Ask about this example…"
-          rows={2}
+          placeholder="Ask a question…"
+          rows={1}
           maxLength={800}
           disabled={busy}
           aria-label="Your question"
         />
-        <button type="submit" style={{ ...primary, opacity: busy || !input.trim() ? 0.5 : 1 }} disabled={busy || !input.trim()}>
-          Send
+        <button
+          type="submit"
+          className="hot-chat-send"
+          disabled={busy || !input.trim()}
+          aria-label="Send"
+        >
+          <IconArrowUp />
         </button>
       </form>
-      <p style={{ ...muted, fontSize: 12, margin: `${theme.space(2)} 0 0` }}>
-        Answers can be wrong — check the code before you rely on it.
+      <p className="hot-chat-disclaimer">
+        AI-generated responses may be inaccurate. Verify critical information before use.
       </p>
     </>
   );
 
   return (
-    <Drawer title="Ask about this example" onClose={onClose} footer={footer}>
-      <div ref={listRef} style={list}>
+    <Drawer
+      title="Ask AI"
+      icon={<IconSparkles size={18} />}
+      label="Ask about this example"
+      onClose={onClose}
+      footer={footer}
+      footerStyle={{ padding: 0, background: theme.color.surfaceRaised }}
+    >
+      <div ref={listRef} className="hot-chat-list">
         {turns.length === 0 && (
-          <div style={{ padding: `${theme.space(1)} 0` }}>
-            <p style={{ ...muted, marginTop: 0 }}>
-              Ask what this example does, what an option means, or ask for a change —
-              answers are grounded in the Handsontable documentation, and any code change is
-              shown for you to apply.
+          <div>
+            <h3 className="hot-chat-welcome-title">How can I help?</h3>
+            <p className="hot-chat-welcome-text">
+              I answer questions about the example you have open — grounded in the
+              Handsontable docs — and any code change arrives as a proposal for you
+              to apply.
             </p>
-            <div style={{ display: "flex", flexDirection: "column", gap: theme.space(2) }}>
+            <div className="hot-panel-menu">
               {SUGGESTIONS.map((s) => (
                 <button
                   key={s}
                   type="button"
-                  className="hot-panel-suggestion"
-                  style={{ ...suggestion, opacity: busy ? 0.5 : 1 }}
+                  className="hot-panel-suggestion hot-panel-menu-item"
+                  style={{ opacity: busy ? 0.5 : 1 }}
                   disabled={busy}
                   onClick={() => void send(s)}
                 >
-                  {s}
+                  <span>{s}</span>
+                  <span className="hot-chat-arrow" aria-hidden="true">→</span>
                 </button>
               ))}
             </div>
@@ -273,36 +289,36 @@ export function ChatPanel({
         )}
 
         {turns.map((turn, i) => (
-          <div key={i} style={turn.role === "user" ? userBubble : assistantBubble}>
+          <div key={i} className={turn.role === "user" ? "hot-chat-bubble" : "hot-chat-answer"}>
             <Markdown text={turn.content} error={turn.error} />
 
             {turn.edits && turn.edits.length > 0 && (
-              <div style={editBox}>
-                <div style={{ fontSize: 12, color: theme.color.textMuted, marginBottom: theme.space(2) }}>
+              <div className="hot-chat-edit-box">
+                <div className="hot-chat-edit-head">
                   {turn.undo ? "Applied to" : "Proposed changes to"} {turn.edits.length} file
                   {turn.edits.length > 1 ? "s" : ""}
                 </div>
                 {turn.edits.map((edit) => (
                   <div key={edit.path} style={{ marginBottom: theme.space(1) }}>
-                    <code style={pathChip}>{edit.path}</code>
-                    {edit.why && <span style={{ ...muted, fontSize: 12, marginLeft: theme.space(2) }}>{edit.why}</span>}
+                    <code className="hot-chat-path-chip">{edit.path}</code>
+                    {edit.why && <span className="hot-chat-edit-why">{edit.why}</span>}
                   </div>
                 ))}
                 <div style={{ display: "flex", gap: theme.space(2), marginTop: theme.space(2) }}>
                   {turn.undo
-                    ? <button type="button" style={ghost} onClick={() => undo(i)}>Undo</button>
-                    : <button type="button" style={primary} onClick={() => apply(i)}>Apply</button>}
+                    ? <button type="button" className="hot-btn-ghost" onClick={() => undo(i)}>Undo</button>
+                    : <button type="button" className="hot-btn-primary" onClick={() => apply(i)}>Apply</button>}
                 </div>
               </div>
             )}
 
             {(turn.references?.length || turn.pages?.length) ? (
-              <div style={{ marginTop: theme.space(2), fontSize: 12 }}>
-                <div style={{ color: theme.color.textMuted, marginBottom: 2 }}>Documentation</div>
+              <div className="hot-chat-docs">
+                <div className="hot-chat-docs-label">Documentation</div>
                 {[...new Set([...(turn.references ?? []), ...(turn.pages ?? []).map((p) => p.url)])]
                   .slice(0, 6)
                   .map((url) => (
-                    <a key={url} href={url} target="_blank" rel="noreferrer" style={docLink}>
+                    <a key={url} href={url} target="_blank" rel="noreferrer" className="hot-chat-doc-link">
                       {(turn.pages ?? []).find((p) => p.url === url)?.title ?? prettyUrl(url)}
                     </a>
                   ))}
@@ -311,7 +327,7 @@ export function ChatPanel({
           </div>
         ))}
 
-        {busy && <div style={{ ...assistantBubble, ...muted }}>{status ?? "Thinking…"}</div>}
+        {busy && <div className="hot-chat-answer hot-chat-muted">{status ?? "Thinking…"}</div>}
       </div>
     </Drawer>
   );
@@ -352,15 +368,15 @@ export function AskAiButton({ open, onToggle }: { open: boolean; onToggle: () =>
       </button>
 
       {show && (
-        <span id="ask-ai-hint" role="tooltip" style={tooltip}>
-          <strong style={{ display: "block", marginBottom: theme.space(1) }}>Ask about this example</strong>
-          <span style={{ display: "block", color: theme.color.textMuted, marginBottom: theme.space(2) }}>
+        <span id="ask-ai-hint" role="tooltip" className="hot-cta-tooltip">
+          <strong>Ask about this example</strong>
+          <span className="hot-cta-tooltip-intro">
             Scoped to the code you have open — not Handsontable in general.
           </span>
-          <span style={tooltipItem}>“What does this example do?”</span>
-          <span style={tooltipItem}>“Make the first two columns frozen” — the edit arrives ready to apply</span>
-          <span style={tooltipItem}>Grounded in the Handsontable docs, with links</span>
-          <span style={{ display: "block", marginTop: theme.space(2), color: theme.color.textMuted }}>
+          <span className="hot-cta-tooltip-item">“What does this example do?”</span>
+          <span className="hot-cta-tooltip-item">“Make the first two columns frozen” — the edit arrives ready to apply</span>
+          <span className="hot-cta-tooltip-item">Grounded in the Handsontable docs, with links</span>
+          <span className="hot-cta-tooltip-note">
             Changes are never applied without you — Apply, then Undo if you don’t like it.
           </span>
         </span>
@@ -373,64 +389,10 @@ const prettyUrl = (url: string) => url.replace(/^https:\/\/handsontable\.com\/do
 
 // ---- Styles ------------------------------------------------------------------
 //
-// The drawer itself — fixed panel, header, close button, composer band — is
-// `Drawer` in the shell now, shared with the style panel (DEV-2209). What is left
-// is the transcript, on the shell's scales: `space(n)` padding, `radius.sm|md`,
-// and 13/12 type. `controlBorder` on control outlines, because the drawer is
-// painted `surfaceRaised` and dark `border` *is* `surfaceRaised`.
-
-/** The transcript is the scroller, not `Drawer`'s body: `listRef.scrollTo` has
- *  to reach the element that actually overflows. A definite `height: 100%`
- *  inside the body's flex track plus its own `overflow` keeps the scroll here
- *  and leaves the body with nothing to scroll. */
-const list: React.CSSProperties = {
-  height: "100%", overflowY: "auto",
-  padding: `${theme.space(3)} ${theme.space(4)}`, fontSize: 13,
-};
-const muted: React.CSSProperties = { color: theme.color.textMuted };
-const userBubble: React.CSSProperties = {
-  background: theme.color.surfaceMuted, borderRadius: theme.radius.md,
-  padding: `${theme.space(2)} ${theme.space(3)}`, margin: `0 0 ${theme.space(3)} auto`,
-  maxWidth: "90%", width: "fit-content",
-};
-const assistantBubble: React.CSSProperties = { padding: `0 0 ${theme.space(3)}`, maxWidth: "100%" };
-const editBox: React.CSSProperties = {
-  border: `1px solid ${theme.color.controlBorder}`, borderRadius: theme.radius.md,
-  padding: theme.space(3), marginTop: theme.space(2), background: theme.color.surfaceMuted,
-};
-const pathChip: React.CSSProperties = {
-  fontFamily: theme.font.mono, fontSize: 12, background: theme.color.surface,
-  border: `1px solid ${theme.color.controlBorder}`, borderRadius: theme.radius.sm,
-  padding: `1px ${theme.space(1)}`,
-};
-const docLink: React.CSSProperties = {
-  display: "block", color: theme.color.accentText, textDecoration: "none", padding: "1px 0",
-};
-const composer: React.CSSProperties = { display: "flex", gap: theme.space(2) };
-const textarea: React.CSSProperties = {
-  flex: 1, resize: "none", fontFamily: theme.font.ui, fontSize: 13,
-  padding: `${theme.space(2)} ${theme.space(2)}`,
-  border: `1px solid ${theme.color.controlBorder}`, borderRadius: theme.radius.md,
-  // Explicit, not the UA's `field` default via `color-scheme`: every other
-  // control in the two panels is painted `surface`, and one that is not looks
-  // like a different control in dark.
-  background: theme.color.surface, color: theme.color.text,
-};
-const primary: React.CSSProperties = {
-  fontFamily: theme.font.ui, fontSize: 13, background: theme.color.accent,
-  color: theme.color.accentContrast, border: "none", borderRadius: theme.radius.sm,
-  padding: `${theme.space(2)} ${theme.space(3)}`, cursor: "pointer",
-};
-const ghost: React.CSSProperties = {
-  fontFamily: theme.font.ui, fontSize: 13, background: theme.color.surface, color: theme.color.text,
-  border: `1px solid ${theme.color.controlBorder}`, borderRadius: theme.radius.sm,
-  padding: `${theme.space(2)} ${theme.space(3)}`, cursor: "pointer",
-};
-/** No `background`: `.hot-panel-suggestion` owns the fill and its rollover, and
- *  an inline one — `ghost`'s `surface` included — would outrank it (ADR-0026). */
-const suggestion: React.CSSProperties = {
-  ...ghost, background: undefined, textAlign: "left", color: theme.color.accentText,
-};
+// The drawer chrome is `Drawer` in the shell (DEV-2209); everything this panel
+// paints lives as classes in `panels.css` — imported once from main.tsx — with
+// only per-instance values (busy opacity, list margins) inline. The one style
+// object left is `askBtn`, the toolbar trigger.
 
 // Deliberately the same neutral treatment as every other toolbar button: this
 // used to carry the accent border and text, which read as the primary action on
@@ -447,17 +409,8 @@ const askBtn: React.CSSProperties = {
   // mark on the bar that could not follow the theme.
   display: "inline-flex", alignItems: "center", gap: theme.space(2),
   height: 36, padding: `0 ${theme.space(3)}`, flex: "0 0 auto",
-  fontFamily: theme.font.ui, fontSize: 13, fontWeight: 600,
+  fontFamily: theme.font.ui, ...theme.type.base, fontWeight: 600,
   background: "transparent", color: theme.color.text,
   border: `1px solid ${theme.color.controlBorder}`, borderRadius: theme.radius.md,
   cursor: "pointer", whiteSpace: "nowrap",
 };
-const tooltip: React.CSSProperties = {
-  position: "absolute", top: `calc(100% + ${theme.space(2)})`, left: 0, zIndex: 950, width: 320,
-  background: theme.color.surfaceRaised, border: `1px solid ${theme.color.controlBorder}`,
-  borderRadius: theme.radius.md, boxShadow: theme.shadow.popover,
-  padding: `${theme.space(2)} ${theme.space(3)}`,
-  fontFamily: theme.font.ui, fontSize: 12, color: theme.color.text,
-  textAlign: "left", whiteSpace: "normal", cursor: "default",
-};
-const tooltipItem: React.CSSProperties = { display: "block", padding: `${theme.space(1)} 0` };
diff --git a/runner/apps/authoring/src/DocsCascader.tsx b/runner/apps/authoring/src/DocsCascader.tsx
index 88b1343eb..8ca763663 100644
--- a/runner/apps/authoring/src/DocsCascader.tsx
+++ b/runner/apps/authoring/src/DocsCascader.tsx
@@ -539,7 +539,7 @@ const s = {
     // holds only because the trigger's wrapper is unpositioned; see the note
     // there before giving anything between here and the pill a `position`.
     width: "100%", boxSizing: "border-box",
-    display: "flex", flexDirection: "column", gap: 10,
+    display: "flex", flexDirection: "column", gap: 8,
     padding: theme.space(2),
     background: theme.color.surfaceRaised,
     border: `1px solid ${theme.color.border}`,
@@ -560,7 +560,7 @@ const s = {
     color: theme.color.textMuted, pointerEvents: "none",
   },
 
-  body: { display: "flex", gap: 10, alignItems: "stretch", maxHeight: BODY_MAX_HEIGHT, minHeight: 0 },
+  body: { display: "flex", gap: 8, alignItems: "stretch", maxHeight: BODY_MAX_HEIGHT, minHeight: 0 },
   // `scrollbarWidth: thin` claws back most of the ~15px a classic scrollbar
   // takes out of the 179 (Windows/Linux always; macOS when "always show
   // scrollbars" is on). The design draws no scrollbar at all because it shows 16
@@ -616,7 +616,7 @@ const s = {
   },
   sep: { color: theme.color.textMuted },
   empty: {
-    padding: `10px ${theme.space(3)}`, color: theme.color.textMuted,
+    padding: `${theme.space(2)} ${theme.space(3)}`, color: theme.color.textMuted,
     fontFamily: theme.font.ui, fontSize: 13,
   },
 } satisfies Record<string, React.CSSProperties>;
diff --git a/runner/apps/authoring/src/Guide.tsx b/runner/apps/authoring/src/Guide.tsx
index cfff9332b..fccf50249 100644
--- a/runner/apps/authoring/src/Guide.tsx
+++ b/runner/apps/authoring/src/Guide.tsx
@@ -347,7 +347,7 @@ const cardHead: CSSProperties = { display: "flex", alignItems: "center", gap: th
 
 const badge = (technical: boolean): CSSProperties => ({
   display: "inline-block",
-  padding: "1px 6px",
+  padding: "1px 8px",
   borderRadius: theme.radius.sm,
   border: `1px solid ${theme.color.border}`,
   background: technical ? theme.color.surfaceSunken : theme.color.accentSoft,
@@ -384,11 +384,11 @@ const cardListItem: CSSProperties = {
   fontSize: 12,
   lineHeight: 1.5,
   color: theme.color.textMuted,
-  paddingLeft: 10,
+  paddingLeft: 12,
   position: "relative",
   // A dash, not a bullet: three of these sit inside a card that is already a list
   // item on the page, and a second bullet level reads as an outline.
-  textIndent: -10,
+  textIndent: -12,
 };
 
 const cardMore: CSSProperties = {
@@ -441,7 +441,7 @@ const contentsLink: CSSProperties = {
 
 const copyButton = (copied: boolean): CSSProperties => ({
   flex: "0 0 auto",
-  padding: "0 3px",
+  padding: "0 4px",
   border: "none",
   background: "transparent",
   color: copied ? theme.color.accentText : theme.color.textMuted,
diff --git a/runner/apps/authoring/src/MarkdownField.tsx b/runner/apps/authoring/src/MarkdownField.tsx
index c93747bec..31c9d8bed 100644
--- a/runner/apps/authoring/src/MarkdownField.tsx
+++ b/runner/apps/authoring/src/MarkdownField.tsx
@@ -151,11 +151,11 @@ const header: CSSProperties = {
 const toolbar: CSSProperties = {
   display: "flex",
   alignItems: "center",
-  gap: 2,
+  gap: 4,
 };
 
 /** A worded button ("Link") needs its own width; the glyph buttons stay square. */
-const wordButton: CSSProperties = { width: "auto", padding: "0 6px" };
+const wordButton: CSSProperties = { width: "auto", padding: "0 8px" };
 
 const toolButton: CSSProperties = {
   display: "inline-flex",
@@ -178,7 +178,7 @@ const previewBox: CSSProperties = {
   minHeight: 120,
   maxHeight: 240,
   overflowY: "auto",
-  padding: "8px 10px",
+  padding: "8px 12px",
   border: `1px solid ${theme.color.controlBorder}`,
   borderRadius: theme.radius.md,
   background: theme.color.surface,
diff --git a/runner/apps/authoring/src/MyDemos.tsx b/runner/apps/authoring/src/MyDemos.tsx
index 6057ee03f..181885661 100644
--- a/runner/apps/authoring/src/MyDemos.tsx
+++ b/runner/apps/authoring/src/MyDemos.tsx
@@ -740,7 +740,7 @@ const content: CSSProperties = {
 const grid: CSSProperties = {
   display: "grid",
   gridTemplateColumns: "repeat(auto-fill, minmax(300px, 334px))",
-  gap: 10,
+  gap: 12,
   alignItems: "start",
 };
 
diff --git a/runner/apps/authoring/src/StylePanel.tsx b/runner/apps/authoring/src/StylePanel.tsx
index 100586cf1..8c46c1c5f 100644
--- a/runner/apps/authoring/src/StylePanel.tsx
+++ b/runner/apps/authoring/src/StylePanel.tsx
@@ -14,10 +14,12 @@ import { useEffect, useMemo, useRef, useState } from "react";
 import {
   Drawer,
   headerLabel,
+  IconArrowUp,
   IconChevronDown,
   IconChevronLeft,
   IconChevronRight,
   IconPalette,
+  IconX,
   theme as ui,
 } from "@handsontable/demo-editor-shell";
 import { reportError } from "./sentry.js";
@@ -162,6 +164,17 @@ export function StylePanel({
   const [prompt, setPrompt] = useState("");
   const [thinking, setThinking] = useState(false);
   const [aiNote, setAiNote] = useState<string | null>(null);
+  // The intro blurb is a dismissible notice: once someone knows what the panel
+  // is, the paragraph is four lines of scroll on every open. Dismissal sticks
+  // across sessions; storage can throw (Safari private mode), and a notice that
+  // reappears there is the acceptable failure.
+  const [introDismissed, setIntroDismissed] = useState(() => {
+    try { return localStorage.getItem(INTRO_DISMISSED_KEY) === "1"; } catch { return false; }
+  });
+  const dismissIntro = () => {
+    setIntroDismissed(true);
+    try { localStorage.setItem(INTRO_DISMISSED_KEY, "1"); } catch { /* keep the session's dismissal */ }
+  };
   const [tab, setTab] = useState<Tab>("foundation");
   /** The component whose sub-panel is open, e.g. "Buttons". */
   const [component, setComponent] = useState<string | null>(null);
@@ -552,6 +565,38 @@ export function StylePanel({
     } catch { /* nothing to clear */ }
   }
 
+  /** The AI tab's composer — visually the chat panel's (`.hot-chat-*`): a flush
+   *  textarea at the bottom of the drawer with the ↑ send inside it. The button
+   *  keeps its accessible name "Style", which is how the E2E_AI spec sends. */
+  const aiComposer = (
+    <form
+      className="hot-chat-composer"
+      onSubmit={(e) => { e.preventDefault(); void describe(prompt); }}
+    >
+      <textarea
+        className="hot-chat-input"
+        value={prompt}
+        onChange={(e) => setPrompt(e.target.value)}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); void describe(prompt); }
+        }}
+        placeholder="retro terminal, corporate blue, dark and compact…"
+        rows={1}
+        maxLength={300}
+        disabled={thinking}
+        aria-label="Describe the style you want"
+      />
+      <button
+        type="submit"
+        className="hot-chat-send"
+        disabled={thinking || !prompt.trim()}
+        aria-label="Style"
+      >
+        <IconArrowUp />
+      </button>
+    </form>
+  );
+
   /** Pinned under the scroll body by `Drawer` — the panel's own actions, plus
    *  whatever the last apply had to say about it. */
   const footer = (
@@ -570,10 +615,10 @@ export function StylePanel({
         </p>
       )}
       <div style={{ display: "flex", gap: ui.space(2), flexWrap: "wrap" }}>
-        <button type="button" style={ghost} onClick={() => setShowCode((v) => !v)}>
+        <button type="button" className="hot-btn-ghost" onClick={() => setShowCode((v) => !v)}>
           {showCode ? "Hide code" : "Copy for my app"}
         </button>
-        <button type="button" style={ghost} onClick={reset} disabled={pristine}>
+        <button type="button" className="hot-btn-ghost" onClick={reset} disabled={pristine}>
           Reset
         </button>
         {/* `textMuted`, not `success`. The literal `#1a8f5a` this replaced was a
@@ -591,7 +636,7 @@ export function StylePanel({
           <pre style={pre}><code>{snippet}</code></pre>
           <button
             type="button"
-            style={ghost}
+            className="hot-btn-ghost"
             onClick={() => void navigator.clipboard?.writeText(snippet)}
           >
             Copy snippet
@@ -603,10 +648,12 @@ export function StylePanel({
 
   return (
     <Drawer
-      title="Style this demo"
+      title="Style"
+      icon={<IconPalette size={18} />}
+      label="Style this demo"
       onClose={onClose}
       subheader={
-        <nav style={tabBar} role="tablist" aria-label="Style panel sections">
+        <nav className="hot-style-tabs" role="tablist" aria-label="Style panel sections">
           {([
             ["foundation", "Foundation"],
             ["common", "Common"],
@@ -617,9 +664,8 @@ export function StylePanel({
               key={key}
               type="button"
               role="tab"
-              className="hot-panel-tab"
+              className="hot-panel-tab hot-style-tab"
               aria-selected={tab === key}
-              style={tabBtn(tab === key)}
               onClick={() => { setTab(key); if (key !== "component") setComponent(null); }}
             >
               {label}
@@ -627,44 +673,45 @@ export function StylePanel({
           ))}
         </nav>
       }
-      footer={footer}
+      // The AI tab swaps the actions band for the chat panel's composer — same
+      // flush field, same ↑ send — so the two assistants read as one product.
+      footer={tab === "ai" ? aiComposer : footer}
+      footerStyle={tab === "ai" ? { padding: 0, background: ui.color.surfaceRaised } : undefined}
     >
-      <div>
-        <p style={intro}>
-          The same theme controls as{" "}
-          <a href="https://theme-builder.handsontable.com/" target="_blank" rel="noreferrer" style={{ color: ui.color.accentText }}>
-            Theme Builder
-          </a>
-          , applied to the example you have open. The theme is written into the demo as{" "}
-          <code style={code}>{themeModulePath(getFiles())}</code> and handed to the grid, so it
-          travels with a download or a share.
-        </p>
+      {/* Top padding here, not on the notice: with the notice dismissed the first
+          section otherwise starts flush against the tab strip's rule. */}
+      <div style={{ paddingTop: ui.space(3) }}>
+        {!introDismissed && (
+          <div className="hot-panel-note" role="note">
+            <p>
+              The same theme controls as{" "}
+              <a href="https://theme-builder.handsontable.com/" target="_blank" rel="noreferrer" style={{ color: ui.color.accentText }}>
+                Theme Builder
+              </a>
+              , applied to the example you have open. The theme is written into the demo as{" "}
+              <code style={code}>{themeModulePath(getFiles())}</code> and handed to the grid, so it
+              travels with a download or a share.
+            </p>
+            <button
+              type="button"
+              className="hot-icon-btn hot-panel-note-close"
+              aria-label="Dismiss this note"
+              onClick={dismissIntro}
+            >
+              <IconX size={16} />
+            </button>
+          </div>
+        )}
 
         {tab === "ai" && (
         <Section title="Describe a style">
-          <form
-            style={{ display: "flex", gap: ui.space(2) }}
-            onSubmit={(e) => { e.preventDefault(); void describe(prompt); }}
-          >
-            <input
-              type="text"
-              style={control}
-              value={prompt}
-              onChange={(e) => setPrompt(e.target.value)}
-              placeholder="retro terminal, corporate blue, dark and compact…"
-              maxLength={300}
-              disabled={thinking}
-              aria-label="Describe the style you want"
-            />
-            <button type="submit" style={{ ...ghost, opacity: thinking || !prompt.trim() ? 0.5 : 1 }} disabled={thinking || !prompt.trim()}>
-              {thinking ? "…" : "Style"}
-            </button>
-          </form>
-          {aiNote && <div style={sectionNote}>{aiNote}</div>}
-          <p style={{ ...note, marginTop: ui.space(3), marginBottom: 0 }}>
-            Describes the whole theme at once — presets, ramps and tokens. Everything it
-            sets shows up in the other tabs, where you can nudge it by hand.
+          <p style={{ ...note, marginTop: 0, marginBottom: 0 }}>
+            Describe the style in the box below — it sets the whole theme at once: presets,
+            ramps and tokens. Everything it sets shows up in the other tabs, where you can
+            nudge it by hand.
           </p>
+          {aiNote && <div style={sectionNote}>{aiNote}</div>}
+          {thinking && <div style={sectionNote}>Styling…</div>}
         </Section>
         )}
 
@@ -672,13 +719,13 @@ export function StylePanel({
             load has settled: it would otherwise flash on every panel open, and
             again whenever `/api/versions` repoints a `next` stamp. */}
         {!loadingPresets && presets.fallback && (
-          <div style={{ ...sectionNote, margin: `0 ${ui.space(4)} ${ui.space(2)}` }}>
+          <div style={{ ...sectionNote, margin: `0 ${ui.space(6)} ${ui.space(2)}` }}>
             Showing Handsontable {presets.version}&rsquo;s defaults — {htVersion}&rsquo;s could not
             be loaded. Overrides you set are unaffected.
           </div>
         )}
         {loadingPresets && (
-          <div style={{ ...sectionNote, margin: `0 ${ui.space(4)} ${ui.space(2)}` }}>
+          <div style={{ ...sectionNote, margin: `0 ${ui.space(6)} ${ui.space(2)}` }}>
             Resolving Handsontable {htVersion} defaults&hellip;
           </div>
         )}
@@ -757,23 +804,34 @@ export function StylePanel({
                 The ramps the tokens derive from. Recolouring the brand here beats overriding a
                 dozen tokens one at a time.
               </p>
-              <label style={row}>
-                <span style={rowLabel}>Brand colour</span>
-                <span style={{ display: "flex", gap: ui.space(1), flex: 1 }}>
-                  <input
-                    type="color"
-                    aria-label="Generate the brand ramp from this colour"
-                    value={brandColour}
-                    onChange={(e) => rampFrom(e.target.value)}
-                    style={swatch}
-                  />
-                  <button type="button" style={{ ...ghost, flex: 1 }} onClick={() => rampFrom(brandColour)}>
-                    Generate all six steps
-                  </button>
-                </span>
-              </label>
               <div style={sectionTitle}>Primary</div>
-              <Ramp steps={PRIMARY_STEPS} prefix="primary" state={state} colors={ctx.colors} onChange={setPalette} />
+              {/* The brand picker leads the primary ramp it generates — one row,
+                  not a row of its own. No "Generate" button either: the chip's
+                  change handler already regenerates all six steps, so the button
+                  re-ran what had just happened. */}
+              <Ramp
+                lead={
+                  <label
+                    style={{ textAlign: "center", marginRight: ui.space(2) }}
+                    title="Brand colour — all six primary steps regenerate from it"
+                  >
+                    <input
+                      type="color"
+                      className="hot-color-input"
+                      style={rampChip}
+                      aria-label="Generate the brand ramp from this colour"
+                      value={brandColour}
+                      onChange={(e) => rampFrom(e.target.value)}
+                    />
+                    <div style={{ ...ui.type.small, color: ui.color.textMuted }}>brand</div>
+                  </label>
+                }
+                steps={PRIMARY_STEPS}
+                prefix="primary"
+                state={state}
+                colors={ctx.colors}
+                onChange={setPalette}
+              />
               <div style={sectionTitle}>Neutral</div>
               <Ramp steps={NEUTRAL_STEPS} prefix="palette" state={state} colors={ctx.colors} onChange={setPalette} />
               <div style={sectionTitle}>Base</div>
@@ -881,14 +939,14 @@ export function StylePanel({
               <p style={{ ...note, marginTop: 0 }}>
                 Per-component tokens. Pick a part of the grid to style it on its own.
               </p>
+              <div className="hot-panel-menu">
               {COMPONENT_SECTIONS.map((section) => {
                 const set = overrideCount(section.groups.flatMap((g) => g.tokens));
                 return (
                   <button
                     key={section.label}
                     type="button"
-                    className="hot-panel-row"
-                    style={componentRow}
+                    className="hot-panel-row hot-panel-menu-item"
                     // Test contract (DEV-2203): a stable accessible name. The
                     // computed name otherwise concatenates the override badge
                     // ("Header 2"), so a role query breaks the moment a token
@@ -905,6 +963,7 @@ export function StylePanel({
                   </button>
                 );
               })}
+              </div>
             </div>
           ) : (
             <div style={{ padding: BODY_PAD }}>
@@ -1001,6 +1060,7 @@ function Ramp({
   state,
   colors,
   onChange,
+  lead,
 }: {
   steps: readonly string[];
   prefix: string;
@@ -1008,12 +1068,16 @@ function Ramp({
   /** The effective colours — preset with the panel's palette layered on. */
   colors: ColorsMap;
   onChange: (key: string, value: string) => void;
+  /** Rendered ahead of the steps, in the same row — the brand picker rides at
+   *  the head of the primary ramp rather than on a row of its own. */
+  lead?: React.ReactNode;
 }) {
   const overridden = steps.filter((step) => state.palette[`${prefix}.${step}`] !== undefined);
 
   return (
     <div style={{ marginBottom: ui.space(3) }}>
       <div style={{ display: "flex", gap: ui.space(1), flexWrap: "wrap" }}>
+        {lead}
         {steps.map((step) => {
           const key = `${prefix}.${step}`;
           const override = state.palette[key];
@@ -1027,23 +1091,30 @@ function Ramp({
             >
               <input
                 type="color"
+                className="hot-color-input"
                 aria-label={key}
                 value={hexInputValue(effective, "#ffffff")}
                 onChange={(e) => onChange(key, e.target.value)}
                 style={{
-                  ...swatch,
-                  width: 26,
-                  flex: "0 0 26px",
-                  border: `${override ? 2 : 1}px solid ${override ? ui.color.accent : ui.color.controlBorder}`,
-                  // A fully transparent preset colour normalises to white, which
-                  // would read as an opaque swatch — the chequer says otherwise.
-                  backgroundImage: isTransparentHex(effective)
-                    ? "linear-gradient(45deg, rgba(128,128,128,.4) 25%, transparent 25% 75%, rgba(128,128,128,.4) 75%)"
-                    : undefined,
-                  backgroundSize: "8px 8px",
+                  // 24px, down from the class's 28: the neutral ramp is eleven
+                  // steps, and 24 + 4px gaps is what fits them on one line of
+                  // the drawer. Chequer for transparent colours — a fully
+                  // transparent preset normalises to white, which would read as
+                  // an opaque swatch. (Overridden steps used to take a 2px
+                  // accent ring; after a brand pick — which overrides all six —
+                  // the whole ramp lit up and read as a selection, not a state.
+                  // "Reset ramp (n)" and the group badge carry the count.)
+                  ...rampChip,
+                  ...(isTransparentHex(effective)
+                    ? {
+                        backgroundImage:
+                          "linear-gradient(45deg, rgba(128,128,128,.4) 25%, transparent 25% 75%, rgba(128,128,128,.4) 75%)",
+                        backgroundSize: "8px 8px",
+                      }
+                    : {}),
                 }}
               />
-              <div style={{ fontSize: 10, color: ui.color.textMuted }}>{step}</div>
+              <div style={{ ...ui.type.small, color: ui.color.textMuted }}>{step}</div>
             </label>
           );
         })}
@@ -1051,7 +1122,8 @@ function Ramp({
       {overridden.length > 0 && (
         <button
           type="button"
-          style={{ ...ghost, marginTop: ui.space(2), fontSize: 12 }}
+          className="hot-btn-ghost"
+          style={{ marginTop: ui.space(2) }}
           // Not the bare word "Reset": the panel footer has one of those, and a
           // second exact match makes every `name: "Reset", exact: true` locator
           // ambiguous.
@@ -1067,7 +1139,7 @@ function Ramp({
 
 function Section({ title, children }: { title: string; children: React.ReactNode }) {
   return (
-    <section style={{ padding: `${ui.space(2)} ${ui.space(4)} ${ui.space(3)}` }}>
+    <section style={{ padding: `${ui.space(2)} ${ui.space(6)} ${ui.space(3)}` }}>
       <div style={sectionTitle}>{title}</div>
       {children}
     </section>
@@ -1132,10 +1204,10 @@ function TokenField({
           {token.type === "color" && (
             <input
               type="color"
+              className="hot-color-input"
               aria-label={`${token.label} colour picker`}
               value={hexInputValue(value || resolved)}
               onChange={(e) => onChange(e.target.value)}
-              style={swatch}
             />
           )}
           <input
@@ -1207,22 +1279,22 @@ export function StyleButton({ open, onToggle, disabled = false, disabledReason }
       </button>
 
       {show && (
-        <span id="style-hint" role="tooltip" style={tooltip}>
+        <span id="style-hint" role="tooltip" className="hot-cta-tooltip">
           {disabled ? (
             <>
-              <strong style={{ display: "block", marginBottom: ui.space(1) }}>Not available here</strong>
+              <strong>Not available here</strong>
               <span style={{ display: "block", color: ui.color.textMuted }}>{disabledReason}</span>
             </>
           ) : (
             <>
-              <strong style={{ display: "block", marginBottom: ui.space(1) }}>Restyle this example</strong>
-              <span style={{ display: "block", color: ui.color.textMuted, marginBottom: ui.space(2) }}>
+              <strong>Restyle this example</strong>
+              <span className="hot-cta-tooltip-intro">
                 Everything Theme Builder does, applied to the demo you have open.
               </span>
-              <span style={tooltipItem}>272 tokens — colours, sizes, typography, per component</span>
-              <span style={tooltipItem}>“Retro amber terminal” — describe it and the grid becomes it</span>
-              <span style={tooltipItem}>Presets, brand ramp, light/dark and density</span>
-              <span style={{ display: "block", marginTop: ui.space(2), color: ui.color.textMuted }}>
+              <span className="hot-cta-tooltip-item">272 tokens — colours, sizes, typography, per component</span>
+              <span className="hot-cta-tooltip-item">“Retro amber terminal” — describe it and the grid becomes it</span>
+              <span className="hot-cta-tooltip-item">Presets, brand ramp, light/dark and density</span>
+              <span className="hot-cta-tooltip-note">
                 Written into the demo as a real module, so it survives Download and Share — and
                 Reset puts everything back.
               </span>
@@ -1246,18 +1318,20 @@ export const STYLE_PANEL_TOKENS = ALL_TOKENS.length;
 // dark `border` *is* `surfaceRaised`, which is what the drawer is painted with.
 
 /** The label column of a `row`, and the indent its hint has to match. One
- *  constant, because they were 130 and 138 by hand and could drift apart. */
-const ROW_LABEL_WIDTH = 130;
+ *  constant, because they were 130 and 138 by hand and could drift apart.
+ *  128, not 130: the panel spaces on the 4px grid. */
+const ROW_LABEL_WIDTH = 128;
 
-/** The inset every section in the body shares. */
-const BODY_PAD = `0 ${ui.space(4)} ${ui.space(3)}`;
+/** The inset every section in the body shares — 24px, the drawer header's and
+ *  the chat transcript's, so the three regions align on one left edge. */
+const BODY_PAD = `0 ${ui.space(6)} ${ui.space(3)}`;
 
 const sectionTitle: React.CSSProperties = { ...headerLabel, display: "block", marginBottom: ui.space(2) };
 // No inline `background` — `.hot-panel-row` owns the fill and its rollover (ADR-0026).
 const groupHeader: React.CSSProperties = {
   display: "flex", alignItems: "center", justifyContent: "space-between", width: "100%",
-  border: "none", cursor: "pointer", padding: `${ui.space(2)} ${ui.space(4)}`,
-  fontFamily: ui.font.ui, fontSize: 13, color: ui.color.text, textAlign: "left",
+  border: "none", cursor: "pointer", padding: `${ui.space(2)} ${ui.space(6)}`,
+  fontFamily: ui.font.ui, ...ui.type.base, color: ui.color.text, textAlign: "left",
 };
 const badge: React.CSSProperties = {
   background: ui.color.accent, color: ui.color.accentContrast, borderRadius: 999,
@@ -1267,52 +1341,45 @@ const row: React.CSSProperties = {
   display: "flex", alignItems: "center", gap: ui.space(2), marginBottom: ui.space(2),
 };
 const rowLabel: React.CSSProperties = {
-  width: ROW_LABEL_WIDTH, flex: `0 0 ${ROW_LABEL_WIDTH}px`, fontSize: 13,
+  width: ROW_LABEL_WIDTH, flex: `0 0 ${ROW_LABEL_WIDTH}px`, ...ui.type.base,
 };
 const control: React.CSSProperties = {
-  flex: 1, minWidth: 0, fontFamily: ui.font.ui, fontSize: 13,
+  flex: 1, minWidth: 0, fontFamily: ui.font.ui, ...ui.type.base,
   padding: `${ui.space(1)} ${ui.space(2)}`,
   border: `1px solid ${ui.color.controlBorder}`, borderRadius: ui.radius.sm,
   color: ui.color.text, background: ui.color.surface,
 };
-const swatch: React.CSSProperties = {
-  width: 30, flex: "0 0 30px", padding: 0, height: 26,
-  border: `1px solid ${ui.color.controlBorder}`, borderRadius: ui.radius.sm,
-  background: ui.color.surface, cursor: "pointer",
-};
 /** The inline "Reset" beside an overridden field — the same affordance the token
  *  rows carry in `theme/controls.tsx`, on the same `accentText`. */
 const resetLink: React.CSSProperties = {
-  border: "none", background: "none", color: ui.color.accentText, fontSize: 12,
+  border: "none", background: "none", color: ui.color.accentText, ...ui.type.base,
   cursor: "pointer", padding: `0 ${ui.space(1)}`, flex: "0 0 auto",
 };
 /** Sits under a control, so it indents past the label column to line up with it. */
 const hint: React.CSSProperties = {
-  fontSize: 12, color: ui.color.textMuted, marginLeft: ROW_LABEL_WIDTH + 8,
+  ...ui.type.base, color: ui.color.textMuted, marginLeft: ROW_LABEL_WIDTH + 8,
 };
 /** The same muted line, but explaining a *section* rather than one control — so no
  *  label column to clear, and a real gap above it. Three call sites used to reach
  *  for `hint` and cancel its indent by hand; the one under the icon tiles didn't,
  *  which left the sentence indented under nothing and 4px off the tiles. */
 const sectionNote: React.CSSProperties = {
-  fontSize: 12, color: ui.color.textMuted, marginTop: ui.space(2),
+  ...ui.type.base, color: ui.color.textMuted, marginTop: ui.space(2),
 };
-/** Matches the "Ask AI" tooltip so the two toolbar CTAs read as a pair. */
-const tooltip: React.CSSProperties = {
-  position: "absolute", top: `calc(100% + ${ui.space(2)})`, left: 0, zIndex: 950, width: 320,
-  background: ui.color.surfaceRaised, border: `1px solid ${ui.color.controlBorder}`,
-  borderRadius: ui.radius.md, boxShadow: ui.shadow.popover,
-  padding: `${ui.space(2)} ${ui.space(3)}`,
-  fontFamily: ui.font.ui, fontSize: 12, color: ui.color.text,
-  textAlign: "left", whiteSpace: "normal", cursor: "default",
+/** Theme Builder's segmented controller — the same muted-track/raised-pill
+ *  recipe the popovers' Common/Pick-color and sizing/density/custom switches
+ *  use (`theme/controls.tsx`), not accent-filled buttons. */
+const segmentedRow: React.CSSProperties = {
+  display: "flex", gap: ui.space(1), padding: ui.space(1),
+  background: ui.color.surfaceMuted, borderRadius: ui.radius.md,
+  marginBottom: ui.space(2),
 };
-const tooltipItem: React.CSSProperties = { display: "block", padding: `${ui.space(1)} 0` };
-const segmentedRow: React.CSSProperties = { display: "flex", gap: ui.space(1), marginBottom: ui.space(2) };
 const segmentBtn = (on: boolean): React.CSSProperties => ({
-  flex: 1, fontSize: 12, padding: `${ui.space(1)} 0`, cursor: "pointer", borderRadius: ui.radius.sm,
+  flex: 1, ...ui.type.base, padding: `${ui.space(1)} 0`, cursor: "pointer", borderRadius: ui.radius.sm,
   textTransform: "capitalize", fontFamily: ui.font.ui,
-  border: `1px solid ${on ? ui.color.accent : ui.color.controlBorder}`,
-  background: on ? ui.color.accent : ui.color.surface, color: on ? ui.color.accentContrast : ui.color.text,
+  border: `1px solid ${on ? ui.color.controlBorder : "transparent"}`,
+  background: on ? ui.color.surfaceRaised : "transparent",
+  color: on ? ui.color.text : ui.color.textMuted,
 });
 const tileRow: React.CSSProperties = { display: "flex", gap: ui.space(2), justifyContent: "space-between" };
 /** No `border-color`: `.hot-panel-tile` carries resting, hover and selected, or
@@ -1331,39 +1398,27 @@ const tile: React.CSSProperties = {
 const tileImg: React.CSSProperties = {
   width: "100%", height: "auto", display: "block", borderRadius: ui.radius.sm,
 };
-const tileLabel: React.CSSProperties = { fontSize: 12, textTransform: "capitalize" };
-const tabBar: React.CSSProperties = {
-  display: "flex", borderBottom: `1px solid ${ui.color.border}`, flex: "0 0 auto",
-  padding: `0 ${ui.space(2)}`, background: ui.color.surfaceRaised,
-};
-// No inline `background` — `.hot-panel-tab` owns it. The accent underline stays
-// here: no rule touches `border-bottom-color`, so it cannot be outranked.
-const tabBtn = (on: boolean): React.CSSProperties => ({
-  flex: 1, padding: `${ui.space(2)} ${ui.space(1)}`, fontSize: 13, cursor: "pointer",
-  border: "none", borderBottom: `2px solid ${on ? ui.color.accent : "transparent"}`,
-  color: on ? ui.color.accentText : ui.color.textMuted, fontWeight: on ? 600 : 400,
-  fontFamily: ui.font.ui,
-});
-// Same split as `groupHeader`: the fill and its rollover live in `.hot-panel-row`.
-const componentRow: React.CSSProperties = {
-  display: "flex", alignItems: "center", justifyContent: "space-between", width: "100%",
-  padding: `${ui.space(2)} ${ui.space(1)}`, fontSize: 13, cursor: "pointer",
-  border: "none", borderBottom: `1px solid ${ui.color.border}`,
-  color: ui.color.text, fontFamily: ui.font.ui, textAlign: "left",
-};
+const tileLabel: React.CSSProperties = { ...ui.type.base, textTransform: "capitalize" };
+// The tab strip and its tabs are `.hot-style-tabs` / `.hot-style-tab` in
+// panels.css — natural-width tabs off the 24px inset, the selected state keyed
+// off `aria-selected` so the markup carries it once.
+// The component list rows are `.hot-panel-menu-item` in panels.css — the chat
+// suggestions' framed-grid recipe, shared so the two lists read as one pattern.
 const backBtn: React.CSSProperties = {
   display: "inline-flex", alignItems: "center", gap: ui.space(1),
-  border: "none", background: "none", color: ui.color.accentText, fontSize: 13,
+  border: "none", background: "none", color: ui.color.accentText, ...ui.type.base,
   cursor: "pointer", padding: `${ui.space(2)} 0`, fontFamily: ui.font.ui,
 };
 const subGroup: React.CSSProperties = { ...headerLabel, display: "block", margin: `${ui.space(3)} 0 ${ui.space(2)}` };
-const note: React.CSSProperties = { fontSize: 12, color: ui.color.textMuted, margin: `0 0 ${ui.space(3)}` };
-/** The panel's opening blurb. It sits directly in the scroll body rather than
- *  inside a Section, so it has to bring its own padding — without it the text
- *  runs edge to edge while everything below it is inset. */
-const intro: React.CSSProperties = {
-  ...note, padding: `${ui.space(3)} ${ui.space(4)} 0`, margin: `0 0 ${ui.space(1)}`,
-};
+const note: React.CSSProperties = { ...ui.type.base, color: ui.color.textMuted, margin: `0 0 ${ui.space(3)}` };
+/** `localStorage` key remembering that the intro notice was dismissed. The
+ *  notice itself is `.hot-panel-note` in panels.css. */
+const INTRO_DISMISSED_KEY = "hot-style-intro-dismissed";
+
+/** Ramp chips, 24px over the class's 28: eleven neutral steps plus 4px gaps is
+ *  exactly what fits one drawer line. Shared with the brand picker at the head
+ *  of the primary ramp, so the row reads as one strip. */
+const rampChip: React.CSSProperties = { width: 24, height: 24, flex: "0 0 24px" };
 const code: React.CSSProperties = {
   fontFamily: ui.font.mono, fontSize: "0.92em", background: ui.color.surface,
   border: `1px solid ${ui.color.controlBorder}`, borderRadius: ui.radius.sm,
@@ -1375,11 +1430,6 @@ const pre: React.CSSProperties = {
   margin: `0 0 ${ui.space(2)}`, maxHeight: 220,
   border: `1px solid ${ui.color.controlBorder}`,
 };
-const ghost: React.CSSProperties = {
-  fontFamily: ui.font.ui, fontSize: 13, background: ui.color.surface, color: ui.color.text,
-  border: `1px solid ${ui.color.controlBorder}`, borderRadius: ui.radius.sm,
-  padding: `${ui.space(1)} ${ui.space(3)}`, cursor: "pointer",
-};
 // The two live in the redesigned 72px top bar, which is `surfaceRaised` and has a
 // dark mode. `#fff` and `border` were both fine on the pre-redesign bar; on this one
 // `#fff` is a white block in dark, and dark `border` *is* `surfaceRaised`, so the
@@ -1392,7 +1442,7 @@ const styleBtn: React.CSSProperties = {
   // mark on the bar that could not follow the theme.
   display: "inline-flex", alignItems: "center", gap: ui.space(2),
   height: 36, padding: `0 ${ui.space(3)}`, flex: "0 0 auto",
-  fontFamily: ui.font.ui, fontSize: 13, fontWeight: 600,
+  fontFamily: ui.font.ui, ...ui.type.base, fontWeight: 600,
   background: "transparent", color: ui.color.text,
   border: `1px solid ${ui.color.controlBorder}`, borderRadius: ui.radius.md,
   cursor: "pointer", whiteSpace: "nowrap",
diff --git a/runner/apps/authoring/src/main.tsx b/runner/apps/authoring/src/main.tsx
index 65ec928e7..9db19676e 100644
--- a/runner/apps/authoring/src/main.tsx
+++ b/runner/apps/authoring/src/main.tsx
@@ -1,6 +1,14 @@
 // Must stay first: initialises error reporting before any other module runs, so a
 // throw during module evaluation is still captured.
 import { Sentry } from "./sentry.js";
+// The code face the design specifies (Figma 48:6719 / 31:6597) — bundled, not a
+// CDN link, so the editor never renders a fallback face first. Loaded here, not
+// in the shell: editor-shell stays a side-effect-free source package, and the
+// `theme.font.mono` stack degrades gracefully anywhere this import is absent.
+import "@fontsource/fira-code/400.css";
+// The drawer panels' stylesheet (Ask AI transcript/composer, CTA tooltips) —
+// classes over inline objects; see panels.css for the rules and their reasons.
+import "./panels.css";
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { ThemeProvider } from "@handsontable/demo-editor-shell";
diff --git a/runner/apps/authoring/src/markdown.tsx b/runner/apps/authoring/src/markdown.tsx
index 67d33f7bd..f9d540967 100644
--- a/runner/apps/authoring/src/markdown.tsx
+++ b/runner/apps/authoring/src/markdown.tsx
@@ -169,7 +169,7 @@ export function Markdown({
             return (
               <List key={key} style={listStyle}>
                 {block.items.map((item, j) => (
-                  <li key={j} style={{ margin: "3px 0" }}>{renderInline(item, `${key}-${j}`)}</li>
+                  <li key={j} style={{ margin: `${theme.space(1)} 0` }}>{renderInline(item, `${key}-${j}`)}</li>
                 ))}
               </List>
             );
@@ -198,7 +198,7 @@ const imageStyle: React.CSSProperties = {
   display: "block",
   width: "100%",
   height: "auto",
-  margin: "10px 0 4px",
+  margin: `${theme.space(2)} 0 ${theme.space(1)}`,
   border: `1px solid ${theme.color.controlBorder}`,
   borderRadius: theme.radius.sm,
   background: theme.color.surfaceSunken,
@@ -213,7 +213,7 @@ const chatParagraphStyle: React.CSSProperties = { margin: "0 0 8px", whiteSpace:
  *  for reviewable diffs, and `pre-wrap` reproduced those wraps on screen — prose that
  *  broke mid-sentence at a width nobody's window happens to be. The source's line
  *  endings are a file-format detail; the reader should never see them. */
-const documentParagraphStyle: React.CSSProperties = { margin: "0 0 10px", whiteSpace: "normal" };
+const documentParagraphStyle: React.CSSProperties = { margin: `0 0 ${theme.space(2)}`, whiteSpace: "normal" };
 
 const codeStyle: React.CSSProperties = {
   fontFamily: theme.font.mono, fontSize: "0.92em", background: theme.color.surfaceMuted,
@@ -222,7 +222,8 @@ const codeStyle: React.CSSProperties = {
 };
 const preStyle: React.CSSProperties = {
   background: theme.color.editorBg, color: theme.color.text, borderRadius: theme.radius.md,
-  padding: 10, overflowX: "auto", fontFamily: theme.font.mono, fontSize: 12, margin: "0 0 8px",
+  padding: theme.space(3), overflowX: "auto", fontFamily: theme.font.mono, ...theme.type.base,
+  margin: `0 0 ${theme.space(2)}`,
 };
 
 /** In a document, most of these blocks are things you *say to Claude*, not code — so
@@ -238,11 +239,10 @@ const documentPreStyle: React.CSSProperties = {
   // meant to read as a control you type into. Light is the same value either way.
   border: `1px solid ${theme.color.controlBorder}`,
   borderRadius: theme.radius.md,
-  padding: "12px 14px",
-  margin: "0 0 12px",
+  padding: `${theme.space(3)} ${theme.space(4)}`,
+  margin: `0 0 ${theme.space(3)}`,
   fontFamily: theme.font.mono,
-  fontSize: 12.5,
-  lineHeight: 1.55,
+  ...theme.type.base,
   whiteSpace: "pre-wrap",
   overflowWrap: "anywhere",
 };
@@ -274,7 +274,7 @@ const linkStyle: React.CSSProperties = { color: theme.color.accentText };
  *  the shell's scale, inside a 400px drawer where two of them are a fraction of a
  *  pixel apart on screen anyway (DEV-2209). */
 const headingStyle: React.CSSProperties = {
-  fontSize: 13, fontWeight: 600, margin: `${theme.space(3)} 0 ${theme.space(1)}`,
+  ...theme.type.base, fontWeight: 600, margin: `${theme.space(3)} 0 ${theme.space(1)}`,
 };
 
 /** Document headings (`document` mode). Sizes step down and the space above each
diff --git a/runner/apps/authoring/src/panels.css b/runner/apps/authoring/src/panels.css
new file mode 100644
index 000000000..f44e8fcaa
--- /dev/null
+++ b/runner/apps/authoring/src/panels.css
@@ -0,0 +1,396 @@
+/* The app-owned drawer panels — Ask AI's transcript/composer and the two toolbar
+   CTA tooltips (shared by Ask AI and Style, which is why they live here and not in
+   Chat.tsx). Part of the move off inline style objects: rules here, per-instance
+   values (busy opacity, drawer width) stay inline at the call site.
+
+   Colours and fonts are `var(--hot-…)` tokens from editor-shell's theme.ts — the
+   mode flip swaps variables, so no rule here may hold a colour literal. Type sizes
+   follow the design's two-step scale (`theme.type`): 12/20 base, 10/20 small.
+   Spacing is on the 4px grid, 8px rhythm.
+
+   `.hot-panel-suggestion` (the fill + rollover) stays in index.html — it is shared
+   with the Style panel's rows and predates this file (ADR-0026). */
+
+/* ── Transcript ─────────────────────────────────────────────────────────── */
+
+/* The scroller is here, not on the drawer body: `listRef.scrollTo` has to reach
+   the element that actually overflows. */
+.hot-chat-list {
+  height: 100%;
+  overflow-y: auto;
+  padding: 24px;
+  font-size: 12px;
+  line-height: 20px;
+}
+.hot-chat-muted { color: var(--hot-color-text-muted); }
+
+/* ── Welcome screen — `.da-welcome` ─────────────────────────────────────── */
+
+.hot-chat-welcome-title {
+  margin: 0 0 8px;
+  font-weight: 600;
+  color: var(--hot-color-text);
+}
+.hot-chat-welcome-text {
+  margin: 0 0 20px;
+  color: var(--hot-color-text-muted);
+}
+
+/* The docs suggestion grid, shared by the chat's suggestions and the Style
+   panel's component list: the container draws top+left, each row right+bottom,
+   so every cell is fully framed and shared edges stay one hairline. On
+   `control-border`, not `border` — the frame is the row's whole affordance, and
+   dark `border` is the drawer's own fill (ADR-0028). */
+.hot-panel-menu {
+  display: flex;
+  flex-direction: column;
+  border-top: 1px solid var(--hot-color-control-border);
+  border-left: 1px solid var(--hot-color-control-border);
+}
+/* No background here — `.hot-panel-suggestion`/`.hot-panel-row` own the fill
+   and its rollover. */
+.hot-panel-menu-item {
+  display: grid;
+  grid-template-columns: 1fr auto;
+  align-items: center;
+  gap: 8px;
+  border: none;
+  border-right: 1px solid var(--hot-color-control-border);
+  border-bottom: 1px solid var(--hot-color-control-border);
+  border-radius: 0;
+  padding: 12px 16px;
+  font-family: var(--hot-font-ui);
+  font-size: 12px;
+  line-height: 20px;
+  text-align: left;
+  color: var(--hot-color-text);
+  cursor: pointer;
+}
+.hot-chat-arrow {
+  color: var(--hot-color-text-muted);
+  font-size: 16px;
+  line-height: 1;
+  transition: color 0.15s;
+}
+.hot-panel-suggestion:hover .hot-chat-arrow { color: var(--hot-color-text); }
+
+/* ── Messages — `.da-msg-user .da-bubble` / `.da-assistant-body` ────────── */
+
+/* Accent block, square corners, ::after drawing the speech tail; the extra
+   bottom margin is the 6px the tail hangs below the box. */
+.hot-chat-bubble {
+  position: relative;
+  background: var(--hot-color-accent);
+  color: var(--hot-color-accent-contrast);
+  border-radius: 0;
+  padding: 8px 12px;
+  margin: 0 0 16px auto;
+  max-width: 85%;
+  width: fit-content;
+}
+.hot-chat-bubble::after {
+  content: '';
+  position: absolute;
+  bottom: -6px;
+  right: 0;
+  width: 0;
+  height: 0;
+  border-left: 6px solid transparent;
+  border-top: 6px solid var(--hot-color-accent);
+}
+.hot-chat-answer {
+  padding: 0 0 16px;
+  max-width: 100%;
+}
+
+/* The proposed-edit card inside an answer. `control-border`, or it dissolves
+   into the muted fill it sits on in dark. */
+.hot-chat-edit-box {
+  border: 1px solid var(--hot-color-control-border);
+  border-radius: 8px;
+  padding: 12px;
+  margin-top: 8px;
+  background: var(--hot-color-surface-muted);
+}
+.hot-chat-edit-head {
+  font-size: 10px;
+  line-height: 20px;
+  color: var(--hot-color-text-muted);
+  margin-bottom: 8px;
+}
+.hot-chat-path-chip {
+  font-family: var(--hot-font-mono);
+  font-size: 12px;
+  background: var(--hot-color-surface);
+  border: 1px solid var(--hot-color-control-border);
+  border-radius: 4px;
+  padding: 0 4px;
+}
+.hot-chat-edit-why {
+  font-size: 10px;
+  line-height: 20px;
+  color: var(--hot-color-text-muted);
+  margin-left: 8px;
+}
+.hot-chat-docs {
+  margin-top: 8px;
+  font-size: 10px;
+  line-height: 20px;
+}
+.hot-chat-docs-label { color: var(--hot-color-text-muted); }
+.hot-chat-doc-link {
+  display: block;
+  color: var(--hot-color-accent-text);
+  text-decoration: none;
+  padding: 1px 0;
+}
+
+/* The panels' shared buttons — Apply/Undo in the chat, the Style footer's
+   actions. Base 12/20 like every control on the design's scale. */
+.hot-btn-primary {
+  font-family: var(--hot-font-ui);
+  font-size: 12px;
+  line-height: 20px;
+  background: var(--hot-color-accent);
+  color: var(--hot-color-accent-contrast);
+  border: none;
+  border-radius: 4px;
+  padding: 8px 12px;
+  cursor: pointer;
+}
+.hot-btn-ghost {
+  font-family: var(--hot-font-ui);
+  font-size: 12px;
+  line-height: 20px;
+  background: var(--hot-color-surface);
+  color: var(--hot-color-text);
+  border: 1px solid var(--hot-color-control-border);
+  border-radius: 4px;
+  padding: 8px 12px;
+  cursor: pointer;
+}
+.hot-btn-ghost:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+/* ── Panel notice — dismissible intro card ──────────────────────────────── */
+
+/* A card, not body copy: `surface-muted` over a `control-border` hairline (the
+   proposed-edit box's recipe), with the ✕ riding `.hot-icon-btn`'s hover. */
+.hot-panel-note {
+  position: relative;
+  margin: 0 24px 4px;
+  padding: 12px;
+  padding-right: 40px;
+  border: 1px solid var(--hot-color-control-border);
+  border-radius: 8px;
+  background: var(--hot-color-surface-muted);
+  font-size: 12px;
+  line-height: 20px;
+  color: var(--hot-color-text-muted);
+}
+.hot-panel-note p { margin: 0; }
+.hot-panel-note-close {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  width: 24px;
+  height: 24px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: none;
+  border-radius: 4px;
+  color: var(--hot-color-text-muted);
+  cursor: pointer;
+}
+
+/* ── Native colour inputs — the ramp editor and hex-row chips ───────────── */
+
+/* The UA draws `input[type=color]` as a bevelled well with its own inner
+   padding, which is what made the ramp rows read as mismatched rectangles. A
+   flat chip instead: the shell's control frame outside, the colour inset 3px
+   with its own small radius — the dropdown swatches' look, on a real input.
+   Both vendor pseudos, or Firefox keeps the bevel. */
+.hot-color-input {
+  width: 28px;
+  height: 28px;
+  flex: 0 0 28px;
+  padding: 0;
+  border: 1px solid var(--hot-color-control-border);
+  border-radius: 4px;
+  background: var(--hot-color-surface);
+  cursor: pointer;
+}
+.hot-color-input::-webkit-color-swatch-wrapper { padding: 3px; }
+.hot-color-input::-webkit-color-swatch { border: none; border-radius: 2px; }
+.hot-color-input::-moz-color-swatch { border: none; border-radius: 2px; }
+
+/* ── Info mark — the ⓘ beside a token label (Theme Builder's row) ───────── */
+
+/* The description rides `data-tip` and paints as an ink-on-surface tooltip
+   above the mark — the inverse pair, like Theme Builder's black bubble. Shown
+   on hover and on keyboard focus; the span is focusable at the call site. */
+.hot-info {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  color: var(--hot-color-text-muted);
+  cursor: help;
+}
+.hot-info:hover::after,
+.hot-info:focus-visible::after {
+  content: attr(data-tip);
+  position: absolute;
+  bottom: calc(100% + 4px);
+  left: -8px;
+  z-index: 40;
+  width: max-content;
+  max-width: 240px;
+  padding: 4px 8px;
+  border-radius: 4px;
+  background: var(--hot-color-text);
+  color: var(--hot-color-surface-raised);
+  font-size: 12px;
+  line-height: 20px;
+  white-space: normal;
+}
+
+/* ── Style panel — tab strip ────────────────────────────────────────────── */
+
+/* Natural-width tabs off the shared 24px inset (the drawer header's and the
+   chat transcript's), the selected state keyed off `aria-selected` so the
+   markup carries it once. No background — `.hot-panel-tab` owns the fill and
+   its rollover (ADR-0026). */
+.hot-style-tabs {
+  display: flex;
+  gap: 8px;
+  padding: 0 24px;
+  flex: 0 0 auto;
+  border-bottom: 1px solid var(--hot-color-border);
+  background: var(--hot-color-surface-raised);
+}
+/* Full-width tabs: each takes an equal share of the strip (inside the 24px
+   inset), so the underline reads as a segment, not an underscore. */
+.hot-style-tab {
+  flex: 1;
+  padding: 8px 0;
+  font-family: var(--hot-font-ui);
+  font-size: 12px;
+  line-height: 20px;
+  border: none;
+  border-bottom: 2px solid transparent;
+  color: var(--hot-color-text-muted);
+  cursor: pointer;
+}
+/* Colour alone marks the active tab — a weight change makes the strip's other
+   labels shift a fraction of a pixel every switch. */
+.hot-style-tab[aria-selected="true"] {
+  border-bottom-color: var(--hot-color-accent);
+  color: var(--hot-color-accent-text);
+}
+
+/* ── Composer — `.da-input` / `.da-send` / `.da-disclaimer` ─────────────── */
+
+.hot-chat-composer {
+  position: relative;
+  display: flex;
+  margin: 0;
+}
+/* Flush with the panel: no border, no fill of its own — the band behind it is the
+   drawer surface. Inset focus ring, not outline: the field meets the panel edge
+   and an outline would clip against it. Right padding clears the send arrow. */
+.hot-chat-input {
+  flex: 1;
+  resize: none;
+  font-family: var(--hot-font-ui);
+  font-size: 12px;
+  line-height: 20px;
+  padding: 12px 48px 12px 24px;
+  border: none;
+  border-radius: 0;
+  min-height: 44px;
+  max-height: 128px;
+  background: transparent;
+  color: var(--hot-color-text);
+  transition: background-color 0.15s, box-shadow 0.15s;
+}
+.hot-chat-input:hover { background: var(--hot-color-hover); }
+.hot-chat-input:focus {
+  outline: none;
+  box-shadow: inset 0 0 0 1px var(--hot-color-accent);
+}
+/* Ink-filled square with the panel surface as its glyph — the docs send button
+   inverts the text/background pair rather than reaching for the accent. Hidden
+   entirely while there is nothing to send, not dimmed: an arrow beside an empty
+   field is a promise it can't keep. */
+.hot-chat-send {
+  position: absolute;
+  right: 8px;
+  bottom: 8px;
+  width: 30px;
+  height: 30px;
+  border-radius: 8px;
+  border: none;
+  background: var(--hot-color-text);
+  color: var(--hot-color-surface-raised);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  transition: opacity 0.15s;
+}
+.hot-chat-send:disabled {
+  opacity: 0;
+  pointer-events: none;
+}
+.hot-chat-disclaimer {
+  margin: 0;
+  padding: 8px 16px 12px;
+  font-size: 10px;
+  line-height: 20px;
+  color: var(--hot-color-text-muted);
+  text-align: center;
+}
+
+/* ── Toolbar CTA tooltips — Ask AI and Style share one treatment ────────── */
+
+.hot-cta-tooltip {
+  position: absolute;
+  top: calc(100% + 8px);
+  left: 0;
+  z-index: 950;
+  width: 320px;
+  background: var(--hot-color-surface-raised);
+  border: 1px solid var(--hot-color-control-border);
+  border-radius: 8px;
+  box-shadow: var(--hot-shadow-popover);
+  padding: 16px;
+  font-family: var(--hot-font-ui);
+  font-size: 12px;
+  line-height: 20px;
+  color: var(--hot-color-text);
+  text-align: left;
+  white-space: normal;
+  cursor: default;
+}
+.hot-cta-tooltip strong {
+  display: block;
+  margin-bottom: 8px;
+}
+.hot-cta-tooltip-intro {
+  display: block;
+  color: var(--hot-color-text-muted);
+  margin-bottom: 16px;
+}
+.hot-cta-tooltip-item {
+  display: block;
+  margin: 0 0 8px;
+}
+.hot-cta-tooltip-note {
+  display: block;
+  color: var(--hot-color-text-muted);
+  margin-top: 8px;
+}
diff --git a/runner/apps/authoring/src/theme/controls.tsx b/runner/apps/authoring/src/theme/controls.tsx
index 4b75940ee..c99f52136 100644
--- a/runner/apps/authoring/src/theme/controls.tsx
+++ b/runner/apps/authoring/src/theme/controls.tsx
@@ -10,14 +10,18 @@
 //
 // Adaptation: theme-builder builds these out of antd (Popover, Segmented,
 // ColorPicker, InputNumber). The runner has no component library, so the
-// pickers are inline disclosures rather than floating popovers — which also
-// behaves better in a 420px side panel than anything that needs positioning.
+// pickers are hand-rolled popovers anchored under their triggers — floating,
+// as Theme Builder's are, since the panel matched its row layout (label + ⓘ
+// left, control right). The known cost: a popover opened at the very bottom
+// of the panel extends the body's scroll rather than flipping upward.
 
 import { useState } from "react";
 import {
   headerLabel,
   IconChevronDown,
+  IconChevronRight,
   IconChevronUp,
+  IconInfoCircle,
   theme as ui,
 } from "@handsontable/demo-editor-shell";
 import type { ColorsMap, TokenMap } from "./presets.js";
@@ -54,8 +58,10 @@ function Chevron({ open }: { open: boolean }) {
   return <Glyph size={14} style={{ color: ui.color.textMuted, flex: "0 0 auto" }} />;
 }
 
-/** Label, description, the control, and a Reset that appears only when the
- *  token is actually overridden. */
+/** Theme Builder's row: label with the description behind an ⓘ on the left,
+ *  the control on the right, and a Reset that appears only when the token is
+ *  actually overridden. The description used to be a line under every control —
+ *  272 rows of always-on hint text; the tooltip shows it on intent instead. */
 function Row({
   token,
   overridden,
@@ -72,16 +78,22 @@ function Row({
     // so `label`-based locators cannot reach it, and the label text ("Vertical")
     // repeats across groups.
     <div style={rowWrap} data-token={token.key}>
-      <div style={rowHead}>
+      <span style={rowLabelCell}>
         <span style={rowLabel} title={token.key}>{token.label}</span>
+        {token.description && (
+          // Focusable, so the tooltip is keyboard-reachable; the CSS lives in
+          // panels.css (`.hot-info`), a ::after no inline style can express.
+          <span className="hot-info" data-tip={token.description} tabIndex={0} role="img" aria-label={token.description}>
+            <IconInfoCircle size={14} />
+          </span>
+        )}
         {overridden && (
           <button type="button" style={resetBtn} onClick={onReset} title={`Reset ${token.key}`}>
             Reset
           </button>
         )}
-      </div>
-      {children}
-      {token.description && <div style={hint}>{token.description}</div>}
+      </span>
+      <div style={rowControl}>{children}</div>
     </div>
   );
 }
@@ -106,7 +118,7 @@ function UnitControl({ token, resolved, onChange }: {
   const unit = token.params?.unit ?? "";
   const numeric = resolved.replace(unit, "").trim();
   return (
-    <span style={{ display: "flex", alignItems: "center", gap: 6 }}>
+    <span style={{ display: "flex", alignItems: "center", gap: 8 }}>
       <input
         type="number"
         style={{ ...control, width: 96 }}
@@ -164,7 +176,7 @@ function SizeControl({ value, resolved, effectiveRef = "", density, sizing, mode
   const [mode, setMode] = useState<SizeMode>(() => modeFor(current, modes));
 
   return (
-    <div>
+    <div style={anchor}>
       <button type="button" style={trigger} onClick={() => setOpen(!open)} aria-expanded={open}>
         <span style={ellipsis}>{resolved || "theme default"}</span>
         <Chevron open={open} />
@@ -233,6 +245,22 @@ function SizeControl({ value, resolved, effectiveRef = "", density, sizing, mode
  * of the `[light, dark]` pair matching the scheme you're looking at, so styling
  * in light mode doesn't quietly rewrite dark mode.
  */
+/** A collapsible swatch group inside the colour dropdown — Theme Builder's
+ *  Base / Palette / Primary sections, chevron and all. */
+function ColorGroup({ label, children }: { label: string; children: React.ReactNode }) {
+  const [open, setOpen] = useState(true);
+  const Glyph = open ? IconChevronDown : IconChevronRight;
+  return (
+    <div>
+      <button type="button" style={groupToggle} onClick={() => setOpen(!open)} aria-expanded={open}>
+        <Glyph size={14} style={{ color: ui.color.textMuted, flex: "0 0 auto" }} />
+        <span>{label}</span>
+      </button>
+      {open && children}
+    </div>
+  );
+}
+
 function ColorControl({ token, value, ctx, resolved, onChange }: {
   token: Token;
   value: TokenValue | undefined;
@@ -241,6 +269,9 @@ function ColorControl({ token, value, ctx, resolved, onChange }: {
   onChange: (v: TokenValue) => void;
 }) {
   const [open, setOpen] = useState(false);
+  // Theme Builder's two-tab dropdown: "Common" is every named colour the theme
+  // already carries, "Pick color" the raw picker (the old "Custom" row).
+  const [pickerTab, setPickerTab] = useState<"common" | "custom">("common");
   const { colors, tokens, colorScheme } = ctx;
   const effective = value ?? tokens[token.key];
   const currentRef = Array.isArray(effective)
@@ -253,9 +284,9 @@ function ColorControl({ token, value, ctx, resolved, onChange }: {
   const base = Object.entries(colors).filter(([k, v]) => typeof v === "string") as [string, string][];
 
   return (
-    <div>
+    <div style={anchor}>
       <button type="button" style={trigger} onClick={() => setOpen(!open)} aria-expanded={open}>
-        <span style={{ display: "flex", alignItems: "center", gap: 6, minWidth: 0 }}>
+        <span style={{ display: "flex", alignItems: "center", gap: 8, minWidth: 0 }}>
           <span style={{ ...swatch, background: resolved || "transparent" }} />
           <span style={ellipsis}>{tokenValueLabel(effective, colorScheme) || "theme default"}</span>
         </span>
@@ -263,58 +294,72 @@ function ColorControl({ token, value, ctx, resolved, onChange }: {
       </button>
       {open && (
         <div style={popover}>
-          {!COMMON_COLORS_KEYS.includes(token.key as (typeof COMMON_COLORS_KEYS)[number]) && (
+          <div style={segmented}>
+            <button type="button" style={segment(pickerTab === "common")} onClick={() => setPickerTab("common")}>
+              Common
+            </button>
+            <button type="button" style={segment(pickerTab === "custom")} onClick={() => setPickerTab("custom")}>
+              Pick color
+            </button>
+          </div>
+          {pickerTab === "common" ? (
             <>
-              <div style={groupLabel}>Common — brings its own light &amp; dark</div>
-              <div style={swatchRow}>
-                {COMMON_COLORS_KEYS.map((key) => (
-                  <button key={key} type="button" title={key}
-                    className="hot-swatch-btn" style={swatchBtn}
-                    data-active={currentRef === `tokens.${key}`}
-                    onClick={() => onChange(`tokens.${key}`)}>
-                    <span style={{
-                      ...swatch,
-                      background: String(resolveTokenValue(tokens[key], { ...ctx, tokens, colors }) ?? "#ccc"),
-                    }} />
-                  </button>
-                ))}
+              {!COMMON_COLORS_KEYS.includes(token.key as (typeof COMMON_COLORS_KEYS)[number]) && (
+                <ColorGroup label="Common">
+                  <div style={swatchRow}>
+                    {COMMON_COLORS_KEYS.map((key) => (
+                      <button key={key} type="button" title={key}
+                        className="hot-swatch-btn" style={swatchBtn}
+                        data-active={currentRef === `tokens.${key}`}
+                        onClick={() => onChange(`tokens.${key}`)}>
+                        <span style={{
+                          ...swatchLg,
+                          background: String(resolveTokenValue(tokens[key], { ...ctx, tokens, colors }) ?? "#ccc"),
+                        }} />
+                      </button>
+                    ))}
+                  </div>
+                </ColorGroup>
+              )}
+              <ColorGroup label="Base">
+                <div style={swatchRow}>
+                  {base.map(([k, v]) => (
+                    <button key={k} type="button" title={k} className="hot-swatch-btn" style={swatchBtn}
+                      data-active={currentRef === `colors.${k}`}
+                      onClick={() => pick(`colors.${k}`)}>
+                      <span style={{ ...swatchLg, background: v }} />
+                    </button>
+                  ))}
+                </div>
+              </ColorGroup>
+              {(["palette", "primary"] as const).map((name) => ramp(name).length > 0 && (
+                <ColorGroup key={name} label={name === "primary" ? "Primary" : "Palette"}>
+                  <div style={swatchRow}>
+                    {ramp(name).map(([step, v]) => (
+                      <button key={step} type="button" title={`${name}.${step}`}
+                        className="hot-swatch-btn" style={swatchBtn}
+                        data-active={currentRef === `colors.${name}.${step}`}
+                        onClick={() => pick(`colors.${name}.${step}`)}>
+                        <span style={{ ...swatchLg, background: v }} />
+                      </button>
+                    ))}
+                  </div>
+                </ColorGroup>
+              ))}
+            </>
+          ) : (
+            <>
+              <div style={groupLabel}>Applies to {colorScheme} mode only</div>
+              <div style={{ display: "flex", gap: 8 }}>
+                <input type="color" className="hot-color-input" aria-label={`${token.label} colour picker`}
+                  value={/^#[0-9a-f]{6}$/i.test(resolved) ? resolved : "#000000"}
+                  onChange={(e) => pick(e.target.value)} />
+                <input type="text" style={control} defaultValue={currentRef.startsWith("colors.") ? "" : currentRef}
+                  placeholder="#rrggbb, rgba(), transparent"
+                  onBlur={(e) => e.target.value && pick(e.target.value)} />
               </div>
             </>
           )}
-          <div style={groupLabel}>Base</div>
-          <div style={swatchRow}>
-            {base.map(([k, v]) => (
-              <button key={k} type="button" title={k} className="hot-swatch-btn" style={swatchBtn}
-                data-active={currentRef === `colors.${k}`}
-                onClick={() => pick(`colors.${k}`)}>
-                <span style={{ ...swatch, background: v }} />
-              </button>
-            ))}
-          </div>
-          {(["primary", "palette"] as const).map((name) => ramp(name).length > 0 && (
-            <div key={name}>
-              <div style={groupLabel}>{name === "primary" ? "Primary" : "Palette"}</div>
-              <div style={swatchRow}>
-                {ramp(name).map(([step, v]) => (
-                  <button key={step} type="button" title={`${name}.${step}`}
-                    className="hot-swatch-btn" style={swatchBtn}
-                    data-active={currentRef === `colors.${name}.${step}`}
-                    onClick={() => pick(`colors.${name}.${step}`)}>
-                    <span style={{ ...swatch, background: v }} />
-                  </button>
-                ))}
-              </div>
-            </div>
-          ))}
-          <div style={groupLabel}>Custom — {colorScheme} only</div>
-          <div style={{ display: "flex", gap: 6 }}>
-            <input type="color" aria-label={`${token.label} colour picker`} style={{ ...swatchInput }}
-              value={/^#[0-9a-f]{6}$/i.test(resolved) ? resolved : "#000000"}
-              onChange={(e) => pick(e.target.value)} />
-            <input type="text" style={control} defaultValue={currentRef.startsWith("colors.") ? "" : currentRef}
-              placeholder="#rrggbb, rgba(), transparent"
-              onBlur={(e) => e.target.value && pick(e.target.value)} />
-          </div>
         </div>
       )}
     </div>
@@ -406,16 +451,21 @@ export function DensitySizeControl({ token, ctx, value, resolved, effectiveRef,
 // `controlBorder`, not `border`, on anything meant to read as an outline: the
 // panel is `surfaceRaised`, and dark `border` *is* `surfaceRaised` (theme.ts).
 
-const rowWrap: React.CSSProperties = { marginBottom: ui.space(3) };
-const rowHead: React.CSSProperties = {
-  display: "flex", alignItems: "center", justifyContent: "space-between",
-  gap: ui.space(2), marginBottom: ui.space(1),
+/** Theme Builder's two columns: label + ⓘ left, a fixed control column right. */
+const rowWrap: React.CSSProperties = {
+  display: "grid", gridTemplateColumns: "minmax(0, 1fr) 176px", alignItems: "center",
+  gap: ui.space(2), marginBottom: ui.space(2),
 };
-const rowLabel: React.CSSProperties = { fontSize: 13, minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" };
+const rowLabelCell: React.CSSProperties = {
+  display: "inline-flex", alignItems: "center", gap: ui.space(1), minWidth: 0,
+};
+/** The popovers' positioning context — each control column anchors its own. */
+const rowControl: React.CSSProperties = { position: "relative", minWidth: 0 };
+const anchor: React.CSSProperties = { position: "relative" };
+const rowLabel: React.CSSProperties = { ...ui.type.base, minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" };
 const ellipsis: React.CSSProperties = { overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" };
-const hint: React.CSSProperties = { fontSize: 12, color: ui.color.textMuted, marginTop: ui.space(1) };
 const control: React.CSSProperties = {
-  flex: 1, minWidth: 0, width: "100%", fontFamily: ui.font.ui, fontSize: 13,
+  flex: 1, minWidth: 0, width: "100%", fontFamily: ui.font.ui, ...ui.type.base,
   padding: `${ui.space(1)} ${ui.space(2)}`,
   border: `1px solid ${ui.color.controlBorder}`, borderRadius: ui.radius.sm,
   color: ui.color.text, background: ui.color.surface,
@@ -428,18 +478,36 @@ const resetBtn: React.CSSProperties = {
   border: "none", background: "none", color: ui.color.accentText, fontSize: 12,
   cursor: "pointer", padding: `0 ${ui.space(1)}`, flex: "0 0 auto",
 };
+/** Floating, Theme Builder-style: anchored under the trigger, right-aligned so
+ *  it can be wider than the control column without leaving the 400px drawer.
+ *  `surfaceRaised` + the popover shadow — the recipe every shell popover uses. */
 const popover: React.CSSProperties = {
-  marginTop: ui.space(2), padding: ui.space(2),
+  position: "absolute", top: "calc(100% + 4px)", right: 0, zIndex: 30,
+  width: 288, maxWidth: "80vw", padding: ui.space(2),
   border: `1px solid ${ui.color.controlBorder}`, borderRadius: ui.radius.md,
-  background: ui.color.surfaceMuted,
+  background: ui.color.surfaceRaised, boxShadow: ui.shadow.popover,
+};
+/** Theme Builder's segmented controller: a muted track, the selected segment a
+ *  raised pill — not the accent-filled buttons this used to draw. */
+const segmented: React.CSSProperties = {
+  display: "flex", gap: ui.space(1), padding: ui.space(1),
+  background: ui.color.surfaceMuted, borderRadius: ui.radius.md,
+  marginBottom: ui.space(2),
 };
-const segmented: React.CSSProperties = { display: "flex", gap: ui.space(1), marginBottom: ui.space(2) };
 const segment = (on: boolean): React.CSSProperties => ({
-  flex: 1, fontSize: 12, padding: `${ui.space(1)} 0`, cursor: "pointer", borderRadius: ui.radius.sm,
-  border: `1px solid ${on ? ui.color.accent : ui.color.controlBorder}`,
-  background: on ? ui.color.accent : ui.color.surface,
-  color: on ? ui.color.accentContrast : ui.color.text,
+  flex: 1, ...ui.type.base, padding: `${ui.space(1)} 0`, cursor: "pointer", borderRadius: ui.radius.sm,
+  textTransform: "capitalize", fontFamily: ui.font.ui,
+  border: `1px solid ${on ? ui.color.controlBorder : "transparent"}`,
+  background: on ? ui.color.surfaceRaised : "transparent",
+  color: on ? ui.color.text : ui.color.textMuted,
+  fontWeight: on ? 600 : 400,
 });
+/** The collapsible group header inside the colour dropdown. */
+const groupToggle: React.CSSProperties = {
+  display: "inline-flex", alignItems: "center", gap: ui.space(1),
+  margin: `${ui.space(1)} 0`, padding: 0, border: "none", background: "none",
+  fontFamily: ui.font.ui, ...ui.type.base, color: ui.color.text, cursor: "pointer",
+};
 const scrollList: React.CSSProperties = { maxHeight: 190, overflowY: "auto" };
 /** The resolved value trailing a scale entry. `textMuted`, not the old
  *  `opacity: 0.6` — it has to stay legible on the hover fill. */
@@ -460,14 +528,12 @@ const swatch: React.CSSProperties = {
   width: 16, height: 16, borderRadius: ui.radius.sm, flex: "0 0 16px",
   border: `1px solid ${ui.color.controlBorder}`, display: "inline-block",
 };
+/** The dropdown's pick targets — Theme Builder draws these at ~28px, and a 16px
+ *  square is a hard thing to hit with a mouse. */
+const swatchLg: React.CSSProperties = { ...swatch, width: 24, height: 24, flex: "0 0 24px" };
 /** Same split as `listItem` — `.hot-swatch-btn` carries the border colour. */
 const swatchBtn: React.CSSProperties = {
   padding: 2, borderRadius: ui.radius.sm, cursor: "pointer", lineHeight: 0,
   borderWidth: 2, borderStyle: "solid", background: "none",
 };
-const swatchInput: React.CSSProperties = {
-  width: 30, flex: "0 0 30px", padding: 0, height: 26,
-  border: `1px solid ${ui.color.controlBorder}`, borderRadius: ui.radius.sm,
-  background: ui.color.surface, cursor: "pointer",
-};
 const unitTag: React.CSSProperties = { fontSize: 12, color: ui.color.textMuted };
diff --git a/runner/e2e/panels.spec.ts b/runner/e2e/panels.spec.ts
index ac7dddb2f..4e706563d 100644
--- a/runner/e2e/panels.spec.ts
+++ b/runner/e2e/panels.spec.ts
@@ -69,23 +69,31 @@ test.describe("drawer chrome", () => {
     expect(style?.width).toBe(400);
   });
 
+  // The full-height drawer (docs-assistant geometry) covers the top bar, so with a
+  // panel open the other trigger is under it and a pointer click is intercepted —
+  // by design. The drawer traps nothing, so the triggers stay keyboard-reachable,
+  // and keyboard activation is the path these two tests now take. The mutual
+  // exclusion they prove is unchanged: App.tsx closes one panel as it opens the other.
+
   test("only one drawer is open at a time", async ({ page }) => {
     await openPlayground(page, "light");
     await page.getByRole("button", { name: "Ask AI", exact: true }).click();
     await expect(page.locator(CHAT)).toBeVisible();
 
-    await page.getByRole("button", { name: "Style", exact: true }).click();
+    await page.getByRole("button", { name: "Style", exact: true }).focus();
+    await page.keyboard.press("Enter");
     await expect(page.locator(STYLE)).toBeVisible();
     await expect(page.locator(CHAT)).toHaveCount(0);
   });
 
-  test("swapping drawers leaves focus on the trigger that was clicked", async ({ page }) => {
+  test("swapping drawers leaves focus on the trigger that was activated", async ({ page }) => {
     await openPlayground(page, "light");
     const askAi = page.getByRole("button", { name: "Ask AI", exact: true });
     const style = page.getByRole("button", { name: "Style", exact: true });
 
     await askAi.click();
-    await style.click();
+    await style.focus();
+    await page.keyboard.press("Enter");
     await expect(page.locator(STYLE)).toBeVisible();
 
     // The closing drawer used to focus *its* trigger on unmount — which happens
@@ -196,7 +204,11 @@ test.describe("dark mode legibility", () => {
     await page.getByRole("button", { name: "Ask AI", exact: true }).click();
     const textarea = await paint(page, `${CHAT} textarea`);
     expect(textarea.background).not.toBe("rgb(255, 255, 255)");
-    expect(textarea.background).toBe("rgb(7, 6, 4)");
+    // Transparent by design since the docs-assistant restyle (`.da-input`): the
+    // composer is flush with the panel, so what must not be white is the fill
+    // actually behind it — the drawer's own `surfaceRaised`.
+    expect(textarea.background).toBe("rgba(0, 0, 0, 0)");
+    expect(textarea.parentBackground).toBe("rgb(34, 34, 34)");
   });
 
   test("control outlines are visible against the surface they sit on", async ({ page }) => {
@@ -281,9 +293,10 @@ test.describe("chat transcript", () => {
     const chipLocator = page.locator(`${CHAT} code`, { hasText: "src/index.tsx" });
     const chip = await paint(page, chipLocator);
     expect(chip.borderColor).toBe("rgb(53, 53, 53)");
-    // And the edit box around it — the nearest ancestor that draws a border —
-    // is the other half of the same hairline: same token, same failure mode.
-    const editBox = await paint(page, chipLocator.locator('xpath=ancestor::div[contains(@style, "border")][1]'));
+    // And the edit box around it — the card the chip sits in — is the other half
+    // of the same hairline: same token, same failure mode. By class since the
+    // panel moved off inline styles (panels.css).
+    const editBox = await paint(page, chipLocator.locator('xpath=ancestor::div[contains(@class, "hot-chat-edit-box")][1]'));
     expect(editBox.borderColor).toBe("rgb(53, 53, 53)");
     expect(editBox.borderColor).not.toBe(editBox.parentBackground);
 
diff --git a/runner/e2e/style-panel.spec.ts b/runner/e2e/style-panel.spec.ts
index 32f716814..9045704a0 100644
--- a/runner/e2e/style-panel.spec.ts
+++ b/runner/e2e/style-panel.spec.ts
@@ -42,13 +42,12 @@ function state(page: Page) {
   return page.evaluate(() => JSON.parse(localStorage.getItem("hot-runner-theme") ?? "null"));
 }
 
-/** A TokenControl row, addressed by the one stable handle it has: the label
- *  span's `title`, which carries the token key (labels repeat — six rows are
- *  called "Background Color"). */
+/** A TokenControl row, addressed by `data-token` — the documented test contract
+ *  on the row (labels repeat — six rows are called "Background Color"). This
+ *  used to walk the row's internal structure (`> div > span[title]`), which the
+ *  Theme Builder relayout broke; the attribute is the hook that can't. */
 function tokenRow(page: Page, key: string) {
-  return page.locator(`${STYLE} div`).filter({
-    has: page.locator(`> div > span[title="${key}"]`),
-  }).last();
+  return page.locator(`${STYLE} [data-token="${key}"]`);
 }
 
 /** The module row landing in the file tree is the apply signal — the panel
diff --git a/runner/packages/editor-shell/src/AccountMenu.tsx b/runner/packages/editor-shell/src/AccountMenu.tsx
index edd794b0f..99efcb97c 100644
--- a/runner/packages/editor-shell/src/AccountMenu.tsx
+++ b/runner/packages/editor-shell/src/AccountMenu.tsx
@@ -224,7 +224,7 @@ const menuRow = (disabled?: boolean): CSSProperties => ({
   color: disabled ? theme.color.textMuted : theme.color.text,
   opacity: disabled ? 0.5 : 1,
   fontFamily: theme.font.ui,
-  fontSize: 13,
+  ...theme.type.base,
   textAlign: "left",
   whiteSpace: "nowrap",
   cursor: disabled ? "default" : "pointer",
diff --git a/runner/packages/editor-shell/src/BoxInfo.tsx b/runner/packages/editor-shell/src/BoxInfo.tsx
index d6e7052b1..94b156b2e 100644
--- a/runner/packages/editor-shell/src/BoxInfo.tsx
+++ b/runner/packages/editor-shell/src/BoxInfo.tsx
@@ -127,8 +127,9 @@ const section: CSSProperties = {
 const body: CSSProperties = {
   display: "flex",
   flexDirection: "column",
-  // 10px is the design's own step here and lands off the 4px scale on purpose.
-  gap: 10,
+  // The frame draws 10 here (48:6755); snapped to the 8px rhythm — the project
+  // spaces on the 4px grid and 10 was one of only two values off it.
+  gap: theme.space(2),
   padding: `${theme.space(2)} ${theme.space(3)} ${theme.space(3)}`,
   background: theme.color.surface,
 };
@@ -146,21 +147,19 @@ const titleText: CSSProperties = {
 const descriptionText = (expanded: boolean): CSSProperties => ({
   margin: 0,
   fontFamily: theme.font.ui,
-  fontSize: 10,
-  lineHeight: "20px",
+  ...theme.type.base,
   color: theme.color.textMuted,
   ...(expanded ? {} : { maxHeight: 100, overflow: "hidden" }),
 });
 
 const moreButton: CSSProperties = {
-  margin: `2px 0 0`,
+  margin: `${theme.space(1)} 0 0`,
   padding: 0,
   border: "none",
   background: "none",
   color: theme.color.accentText,
   fontFamily: theme.font.ui,
-  fontSize: 10,
-  lineHeight: "16px",
+  ...theme.type.row,
   cursor: "pointer",
 };
 
@@ -188,7 +187,6 @@ const badgeLabel: CSSProperties = {
 const createdText: CSSProperties = {
   margin: 0,
   fontFamily: theme.font.ui,
-  fontSize: 10,
-  lineHeight: "20px",
+  ...theme.type.base,
   color: theme.color.textMuted,
 };
diff --git a/runner/packages/editor-shell/src/CodeEditor.tsx b/runner/packages/editor-shell/src/CodeEditor.tsx
index e5bb01513..51e519381 100644
--- a/runner/packages/editor-shell/src/CodeEditor.tsx
+++ b/runner/packages/editor-shell/src/CodeEditor.tsx
@@ -1,11 +1,12 @@
 import { useCallback, useEffect, useMemo, useRef } from "react";
-import CodeMirror, { type BasicSetupOptions, type EditorView, type ViewUpdate } from "@uiw/react-codemirror";
+import CodeMirror, { EditorView, Prec, type BasicSetupOptions, type ViewUpdate } from "@uiw/react-codemirror";
 import { githubDark, githubLight } from "@uiw/codemirror-theme-github";
 import { javascript } from "@codemirror/lang-javascript";
 import { html } from "@codemirror/lang-html";
 import { css } from "@codemirror/lang-css";
 import { json } from "@codemirror/lang-json";
 import { vue } from "@codemirror/lang-vue";
+import { theme } from "./theme.js";
 import { useTheme } from "./useTheme.js";
 
 function languageFor(path: string) {
@@ -41,10 +42,88 @@ function languageFor(path: string) {
 const BASIC_SETUP = {
   lineNumbers: true,
   highlightActiveLine: true,
-  foldGutter: true,
+  // The designed gutter (48:6738) is line numbers alone — the fold column made it a
+  // two-column strip the design does not have. Folding itself survives: the default
+  // keymap's fold bindings don't ride on the gutter.
+  foldGutter: false,
   autocompletion: true,
 } as const satisfies BasicSetupOptions;
 
+/** The editor pane as the design draws it (Figma 48:6719 light / 31:6597 dark):
+ *  Fira Code 12/20, a 16px inset all around, and a chromeless gutter — no fill, no
+ *  divider, numbers right-aligned at 40% of the ink colour. Split from `GUTTER_INK`
+ *  below because everything here is mode-invariant or var()-resolved. `Prec.high`
+ *  is not decoration: the `theme` prop outranks plain `extensions` entries, so
+ *  without it githubDark's #0d1117 background wins over `&`'s (measured) — the
+ *  design's dark editor is `editorBg` (#19191c). */
+const CHROME = {
+  "&": { fontSize: "12px", backgroundColor: "var(--hot-color-editor-bg)" },
+  ".cm-scroller": { fontFamily: theme.font.mono, lineHeight: "20px" },
+  ".cm-content": { padding: "16px 0" },
+  ".cm-line": { padding: "0 16px" },
+  ".cm-gutters": { backgroundColor: "transparent", border: "none", paddingLeft: "16px" },
+  // Default is "0 3px 0 5px", which would break the designed 16px number→code gap.
+  ".cm-lineNumbers .cm-gutterElement": { padding: "0" },
+  ".cm-activeLineGutter": { backgroundColor: "transparent" },
+
+  // The Mod-F search panel (@codemirror/search's stock DOM), which otherwise
+  // ships CodeMirror's UA-grey look: gradient buttons, unstyled fields, a bare ×.
+  // Restated in the shell's own idiom — `surfaceRaised` band over a hairline,
+  // controls as `surface` + `controlBorder` + 4px radius at 12/20, the same
+  // recipe as `.hot-btn-ghost` and the panel selects. All var()-resolved, so one
+  // block serves both modes. Flex + gap replaces the markup's whitespace-node
+  // spacing, which is what put every control on its own arbitrary offset.
+  ".cm-panels": { backgroundColor: "var(--hot-color-surface-raised)", color: "var(--hot-color-text)" },
+  ".cm-panels-bottom": { borderTop: "1px solid var(--hot-color-control-border)" },
+  ".cm-panel.cm-search": {
+    display: "flex", flexWrap: "wrap", alignItems: "center", gap: "8px",
+    padding: "8px 16px", paddingRight: "40px",
+    fontFamily: "var(--hot-font-ui)", fontSize: "12px", lineHeight: "20px",
+  },
+  // The markup separates its find and replace rows with a lone <br>; as a flex
+  // item that renders as nothing and the two rows shuffle together at narrow
+  // pane widths. A 100% basis turns it back into a row break.
+  ".cm-panel.cm-search br": { flexBasis: "100%", height: "0" },
+  ".cm-panel.cm-search .cm-textfield": {
+    font: "inherit", flex: "1 1 128px", width: "auto", margin: "0", padding: "4px 8px",
+    background: "var(--hot-color-surface)", color: "var(--hot-color-text)",
+    border: "1px solid var(--hot-color-control-border)", borderRadius: "4px",
+  },
+  ".cm-panel.cm-search .cm-textfield:focus": {
+    outline: "none", borderColor: "var(--hot-color-accent)",
+  },
+  ".cm-panel.cm-search .cm-button": {
+    font: "inherit", margin: "0", padding: "4px 8px", cursor: "pointer",
+    // The stock look is a grey gradient; `none` alone leaves it showing.
+    backgroundImage: "none",
+    background: "var(--hot-color-surface)", color: "var(--hot-color-text)",
+    border: "1px solid var(--hot-color-control-border)", borderRadius: "4px",
+    textTransform: "capitalize",
+  },
+  ".cm-panel.cm-search .cm-button:active": { background: "var(--hot-color-surface-muted)" },
+  ".cm-panel.cm-search label": {
+    display: "inline-flex", alignItems: "center", gap: "4px",
+    fontSize: "12px", textTransform: "capitalize", cursor: "pointer",
+  },
+  ".cm-panel.cm-search input[type=checkbox]": {
+    margin: "0", accentColor: "var(--hot-color-accent)",
+  },
+  ".cm-panel.cm-search button[name=close]": {
+    position: "absolute", top: "8px", right: "8px",
+    width: "24px", height: "24px", padding: "0",
+    display: "inline-flex", alignItems: "center", justifyContent: "center",
+    background: "transparent", border: "none", borderRadius: "4px",
+    color: "var(--hot-color-text-muted)", fontSize: "16px", cursor: "pointer",
+  },
+  ".cm-panel.cm-search button[name=close]:hover": {
+    background: "var(--hot-color-hover)", color: "var(--hot-color-text)",
+  },
+} as const;
+/** 40% of black/white per mode — the one part of the chrome no shell token or
+ *  var() covers, hence two theme instances instead of one. */
+const chromeLight = Prec.high(EditorView.theme({ ...CHROME, ".cm-lineNumbers": { color: "rgba(0, 0, 0, 0.4)" } }));
+const chromeDark = Prec.high(EditorView.theme({ ...CHROME, ".cm-lineNumbers": { color: "rgba(255, 255, 255, 0.4)" } }));
+
 /** Caret position, 1-based, as the status bar shows it. */
 export interface CursorPosition {
   line: number;
@@ -78,8 +157,11 @@ export function CodeEditor({
   onCursorChange,
   onCreateEditor,
 }: CodeEditorProps) {
-  const extensions = useMemo(() => languageFor(path), [path]);
   const { mode } = useTheme();
+  const extensions = useMemo(
+    () => [...languageFor(path), mode === "dark" ? chromeDark : chromeLight],
+    [path, mode],
+  );
 
   // Both handlers are insulated behind a ref, because `useCodeMirror` reconfigures the
   // whole extension set from an effect that lists `onChange` and `onUpdate` among its
@@ -121,7 +203,7 @@ export function CodeEditor({
     <CodeMirror
       value={value}
       height="100%"
-      style={{ height: "100%", fontSize: 13 }}
+      style={{ height: "100%" }}
       theme={mode === "dark" ? githubDark : githubLight}
       extensions={extensions}
       editable={!readOnly}
diff --git a/runner/packages/editor-shell/src/Dependencies.tsx b/runner/packages/editor-shell/src/Dependencies.tsx
index ac6af5186..7121df673 100644
--- a/runner/packages/editor-shell/src/Dependencies.tsx
+++ b/runner/packages/editor-shell/src/Dependencies.tsx
@@ -84,15 +84,14 @@ const body: CSSProperties = {
 const row: CSSProperties = {
   display: "flex",
   alignItems: "center",
-  gap: 10,
+  gap: theme.space(2),
   padding: `${theme.space(2)} ${theme.space(3)}`,
   overflow: "clip",
 };
 
 const nameLink: CSSProperties = {
   fontFamily: theme.font.ui,
-  fontSize: 10,
-  lineHeight: "16px",
+  ...theme.type.row,
   color: theme.color.text,
   textDecoration: "none",
   flex: "0 0 auto",
@@ -100,8 +99,7 @@ const nameLink: CSSProperties = {
 
 const urlText: CSSProperties = {
   fontFamily: theme.font.mono,
-  fontSize: 10,
-  lineHeight: "16px",
+  ...theme.type.row,
   color: theme.color.textMuted,
   overflow: "hidden",
   textOverflow: "ellipsis",
diff --git a/runner/packages/editor-shell/src/Drawer.tsx b/runner/packages/editor-shell/src/Drawer.tsx
index b3e6c68ec..97111a7aa 100644
--- a/runner/packages/editor-shell/src/Drawer.tsx
+++ b/runner/packages/editor-shell/src/Drawer.tsx
@@ -17,12 +17,12 @@
 import {
   useEffect,
   useRef,
+  useState,
   type CSSProperties,
   type ReactNode,
 } from "react";
 import { IconX } from "./icons/index.js";
-import { s } from "./styles.js";
-import { theme } from "./theme.js";
+import { installCss, theme } from "./theme.js";
 
 /** Both drawers, one width. Ask AI shipped at 400 and Style at 380; the style
  *  panel is the one with a 130px label column beside a control, and it was the
@@ -30,8 +30,11 @@ import { theme } from "./theme.js";
 export const DRAWER_WIDTH = 400;
 
 export interface DrawerProps {
-  /** Rendered in the title row, 18/600, as `Dialog` draws it. */
+  /** Rendered in the title row, 15/600 with an optional leading icon — the docs
+   *  assistant's title treatment (`.da-title`), which these panels now mirror. */
   title: string;
+  /** Drawn before the title, 8px off it — the panel's identity mark. */
+  icon?: ReactNode;
   /** The panel's accessible name. Defaults to `title`; the two panels give the
    *  fuller sentence their `aside` carried before ("Ask about this example"). */
   label?: string;
@@ -44,20 +47,39 @@ export interface DrawerProps {
   subheader?: ReactNode;
   /** Pinned below the scrolling body, on `surfaceMuted`. */
   footer?: ReactNode;
+  /** Merged over the footer band's own style — the chat panel's composer is
+   *  full-bleed on `surface`, where the style panel's buttons keep the padded
+   *  `surfaceMuted` band. */
+  footerStyle?: CSSProperties;
   width?: number;
 }
 
 export function Drawer({
   title,
+  icon,
   label,
   onClose,
   children,
   subheader,
   footer,
+  footerStyle,
   width = DRAWER_WIDTH,
 }: DrawerProps) {
   const panelRef = useRef<HTMLElement | null>(null);
 
+  // Slide-in from the right, as the docs assistant enters (`.da-panel`'s 0.2s
+  // transform). The panel mounts offscreen and moves to 0 one frame later — a
+  // transition needs a painted "from" state, and setting the resting transform
+  // in the same render as the mount would skip the animation entirely. Close is
+  // an unmount in App.tsx, so there is no slide-out; matching the docs' exit
+  // would mean keeping closed drawers mounted, which is a bigger contract change
+  // than an entrance animation justifies.
+  const [entered, setEntered] = useState(false);
+  useEffect(() => {
+    const raf = requestAnimationFrame(() => setEntered(true));
+    return () => cancelAnimationFrame(raf);
+  }, []);
+
   /**
    * Who had focus when this drawer opened — captured **during the first render**,
    * not in a mount effect, and restored only if focus is still ours to give back.
@@ -105,13 +127,21 @@ export function Drawer({
   }, [onClose]);
 
   return (
-    <aside ref={panelRef} style={{ ...panel, width }} aria-label={label ?? title}>
-      <header style={titleRow}>
-        <h2 style={heading}>{title}</h2>
+    <aside
+      ref={panelRef}
+      className="hot-drawer"
+      data-entered={entered || undefined}
+      style={{ width }}
+      aria-label={label ?? title}
+    >
+      <header className="hot-drawer-header">
+        <h2 className="hot-drawer-title">
+          {icon}
+          {title}
+        </h2>
         <button
           type="button"
-          className="hot-icon-btn"
-          style={closeButton}
+          className="hot-icon-btn hot-drawer-close"
           onClick={onClose}
           aria-label={`Close ${title.toLowerCase()}`}
         >
@@ -122,85 +152,44 @@ export function Drawer({
       {subheader}
 
       {/* The only scrolling region: title row, subheader and footer stay put. */}
-      <div style={body}>{children}</div>
+      <div className="hot-drawer-body">{children}</div>
 
-      {footer !== undefined && <footer style={foot}>{footer}</footer>}
+      {footer !== undefined && <footer className="hot-drawer-foot" style={footerStyle}>{footer}</footer>}
     </aside>
   );
 }
 
-// `zIndex` 900 — under `Dialog`'s 1000. A dialog opened from inside a drawer
-// (Share, from the preview bar) has to paint above it.
+// A real stylesheet, not inline objects (the app-wide move off inline styles):
+// registered once at module scope through `installCss`, colours as `var(--hot-…)`
+// references so the mode flip keeps working. Only per-instance values stay inline
+// — `width` (a prop) and the chat panel's `footerStyle` override.
 //
-// It starts *below* the 72px top bar rather than at `top: 0`, which is what both
-// panels used to do. Covering the bar covered their own triggers: with a drawer
-// open, the other panel's button — and the open one's own toggle — sat under the
-// panel, and Playwright reported the `<h2>` intercepting the click. Mutually
-// exclusive panels you cannot switch between with the mouse are only mutually
-// exclusive on paper (Escape and ✕ were the only ways out). Height follows, or the
-// panel would overhang the viewport by the height of the bar.
-const panel: CSSProperties = {
-  position: "fixed",
-  top: s.topBar.height,
-  right: 0,
-  height: `calc(100% - ${s.topBar.height}px)`,
-  maxWidth: "95vw",
-  zIndex: 900,
-  display: "flex",
-  flexDirection: "column",
-  // `controlBorder`, not `border`: in dark, `border` *is* `surfaceRaised`, so the
-  // drawer's own edge against the workspace would vanish (theme.ts, ADR-0028).
-  borderLeft: `1px solid ${theme.color.controlBorder}`,
-  background: theme.color.surfaceRaised,
-  boxShadow: theme.shadow.panel,
-  color: theme.color.text,
-  fontFamily: theme.font.ui,
-};
-
-const titleRow: CSSProperties = {
-  display: "flex",
-  alignItems: "center",
-  justifyContent: "space-between",
-  gap: theme.space(3),
-  flex: "0 0 auto",
-  padding: `${theme.space(3)} ${theme.space(4)}`,
-  // A divider between two same-tone regions, so `border` is right here — the rule
-  // reads in both modes and `controlBorder` would make it shout (ADR-0028).
-  borderBottom: `1px solid ${theme.color.border}`,
-};
-
-const heading: CSSProperties = {
-  margin: 0,
-  fontSize: 18,
-  fontWeight: 600,
-  color: theme.color.text,
-};
-
-// No inline `background`: it would outrank `.hot-icon-btn:hover` (ADR-0026).
-const closeButton: CSSProperties = {
-  display: "inline-flex",
-  alignItems: "center",
-  justifyContent: "center",
-  width: 28,
-  height: 28,
-  flex: "0 0 auto",
-  marginRight: -4,
-  padding: 0,
-  border: "none",
-  borderRadius: theme.radius.md,
-  color: theme.color.textMuted,
-  cursor: "pointer",
-};
-
-const body: CSSProperties = {
-  flex: 1,
-  minHeight: 0,
-  overflowY: "auto",
-};
-
-const foot: CSSProperties = {
-  flex: "0 0 auto",
-  padding: `${theme.space(3)} ${theme.space(4)}`,
-  borderTop: `1px solid ${theme.color.border}`,
-  background: theme.color.surfaceMuted,
-};
+// The choices the rules encode:
+//  * `z-index` 900 — under `Dialog`'s 1000. A dialog opened from inside a drawer
+//    (Share, from the preview bar) has to paint above it.
+//  * Full viewport height, over the 72px top bar — the docs assistant's geometry
+//    (`.da-panel[data-open]`), adopted deliberately after shipping the
+//    below-the-bar variant first. The cost is known and accepted: with a drawer
+//    open both panel triggers sit under it, so switching panels by pointer means
+//    closing first — the same trade the docs panel makes with its own header. The
+//    triggers stay keyboard-reachable; the drawer is non-modal and traps nothing.
+//  * Entrance is the docs assistant's 0.2s slide, transform-only so nothing
+//    inside reflows; `data-entered` flips one frame after mount so the
+//    transition has a painted "from" state.
+//  * `controlBorder` on the panel edge and both rules, not `border`: in dark,
+//    `border` *is* `surfaceRaised`, so all three hairlines would vanish
+//    (ADR-0028). In light the two tokens share a value.
+//  * The title is `type.base` at 600 with the icon inline (`.da-title`) — the
+//    design's scale tops out at 12px (48:6560), so no third size for a heading.
+//  * `.hot-drawer-close` sets no background: it would outrank
+//    `.hot-icon-btn:hover` (ADR-0026).
+const DRAWER_CSS = `
+.hot-drawer{position:fixed;top:0;right:0;height:100%;max-width:95vw;z-index:900;display:flex;flex-direction:column;border-left:1px solid ${theme.color.controlBorder};background:${theme.color.surfaceRaised};box-shadow:${theme.shadow.panel};color:${theme.color.text};font-family:${theme.font.ui};transition:transform 0.2s ease;transform:translateX(100%)}
+.hot-drawer[data-entered]{transform:translateX(0)}
+.hot-drawer-header{display:flex;align-items:center;justify-content:space-between;gap:${theme.space(3)};flex:0 0 auto;padding:${theme.space(3)} ${theme.space(6)};border-bottom:1px solid ${theme.color.controlBorder}}
+.hot-drawer-title{display:flex;align-items:center;gap:${theme.space(2)};margin:0;font-size:${theme.type.base.fontSize}px;line-height:${theme.type.base.lineHeight};font-weight:600;color:${theme.color.text}}
+.hot-drawer-close{display:inline-flex;align-items:center;justify-content:center;width:28px;height:28px;flex:0 0 auto;margin-right:-4px;padding:0;border:none;border-radius:${theme.radius.md};color:${theme.color.textMuted};cursor:pointer}
+.hot-drawer-body{flex:1;min-height:0;overflow-y:auto}
+.hot-drawer-foot{flex:0 0 auto;padding:${theme.space(3)} ${theme.space(6)};border-top:1px solid ${theme.color.controlBorder};background:${theme.color.surfaceMuted}}
+`;
+installCss("hot-drawer-css", DRAWER_CSS);
diff --git a/runner/packages/editor-shell/src/EditorTabs.tsx b/runner/packages/editor-shell/src/EditorTabs.tsx
index 431a90283..d277386d7 100644
--- a/runner/packages/editor-shell/src/EditorTabs.tsx
+++ b/runner/packages/editor-shell/src/EditorTabs.tsx
@@ -234,7 +234,11 @@ const tab = (isFirst: boolean): CSSProperties => ({
   display: "flex",
   alignItems: "center",
   gap: 4,
-  padding: 6,
+  // 4, not the frame's 6 (48:6724): the strip is a fixed 36px and the file icon a
+  // fixed 24px, so 6 was the only value that filled it exactly — but the project
+  // spaces on a 4px grid, and with `alignItems: center` the icon centres itself in
+  // the 28px content box just the same.
+  padding: theme.space(1),
   boxSizing: "border-box",
   // Without this, tabs compress to fit instead of overflowing and the strip never
   // scrolls.
diff --git a/runner/packages/editor-shell/src/FileTree.tsx b/runner/packages/editor-shell/src/FileTree.tsx
index 89b6d9322..c6c3768c2 100644
--- a/runner/packages/editor-shell/src/FileTree.tsx
+++ b/runner/packages/editor-shell/src/FileTree.tsx
@@ -692,8 +692,7 @@ const slot: CSSProperties = {
 
 const label = (strong: boolean): CSSProperties => ({
   fontFamily: theme.font.ui,
-  fontSize: 10,
-  lineHeight: "16px",
+  ...theme.type.row,
   color: strong ? theme.color.text : theme.color.textMuted,
   overflow: "hidden",
   textOverflow: "ellipsis",
@@ -718,14 +717,13 @@ const dropHint: CSSProperties = {
   right: theme.space(3),
   bottom: 4,
   margin: 0,
-  padding: "4px 6px",
+  padding: `${theme.space(1)} ${theme.space(2)}`,
   borderRadius: theme.radius.sm,
   border: `1px solid ${theme.color.accentBorder}`,
   background: theme.color.surfaceRaised,
   color: theme.color.accentText,
   fontFamily: theme.font.ui,
-  fontSize: 10,
-  lineHeight: "16px",
+  ...theme.type.row,
   whiteSpace: "nowrap",
   overflow: "hidden",
   textOverflow: "ellipsis",
@@ -736,15 +734,13 @@ const dropHint: CSSProperties = {
 const noteText: CSSProperties = {
   margin: `2px ${theme.space(3)}`,
   fontFamily: theme.font.ui,
-  fontSize: 10,
-  lineHeight: "14px",
+  ...theme.type.row,
   color: theme.color.textMuted,
 };
 
 const confirmBody: CSSProperties = {
   margin: 0,
-  fontSize: 13,
-  lineHeight: 1.5,
+  ...theme.type.base,
   color: theme.color.textMuted,
 };
 
@@ -765,7 +761,7 @@ const ghostButton: CSSProperties = {
   background: "transparent",
   color: theme.color.text,
   fontFamily: theme.font.ui,
-  fontSize: 13,
+  ...theme.type.base,
   cursor: "pointer",
 };
 
@@ -783,7 +779,7 @@ const editInput: CSSProperties = {
   boxSizing: "border-box",
   fontFamily: theme.font.mono,
   fontSize: 12,
-  padding: "4px 6px",
+  padding: `${theme.space(1)} ${theme.space(2)}`,
   border: `1px solid ${theme.color.accent}`,
   borderRadius: theme.radius.sm,
   // Raised, not `surface`: this floats over the recessed sidebar, which is
diff --git a/runner/packages/editor-shell/src/PreviewBar.tsx b/runner/packages/editor-shell/src/PreviewBar.tsx
index 0befdf8c6..f354c0e73 100644
--- a/runner/packages/editor-shell/src/PreviewBar.tsx
+++ b/runner/packages/editor-shell/src/PreviewBar.tsx
@@ -283,17 +283,22 @@ function Notice({ text }: { text: string }) {
   );
 }
 
+/** Square and the full 36px of the bar — a flush field in the bar's own band,
+ *  like the chat composer, not a floating pill. The hairline is an inset
+ *  box-shadow rather than a border so the field's box stays exactly the bar's
+ *  height with no double edge against the bar's own rules. */
 const customVersion: React.CSSProperties = {
   width: 181,
-  height: 26,
+  height: "100%",
   flex: "0 0 auto",
-  margin: `0 ${theme.space(2)}`,
+  margin: 0,
   padding: `0 ${theme.space(2)}`,
-  borderRadius: theme.radius.md,
-  border: `1px solid ${theme.color.border}`,
+  borderRadius: 0,
+  border: "none",
+  boxShadow: `inset 0 0 0 1px ${theme.color.controlBorder}`,
   background: theme.color.surface,
   color: theme.color.text,
   fontFamily: theme.font.mono,
-  fontSize: 12,
+  ...theme.type.base,
   boxSizing: "border-box",
 };
diff --git a/runner/packages/editor-shell/src/PreviewPane.tsx b/runner/packages/editor-shell/src/PreviewPane.tsx
index dea4b8a94..4b44fa013 100644
--- a/runner/packages/editor-shell/src/PreviewPane.tsx
+++ b/runner/packages/editor-shell/src/PreviewPane.tsx
@@ -208,7 +208,7 @@ const overlay: CSSProperties = {
   color: theme.color.text,
 };
 
-const headline: CSSProperties = { margin: 0, fontSize: 13 };
+const headline: CSSProperties = { margin: 0, ...theme.type.base };
 
 const syncPill: CSSProperties = {
   position: "absolute",
@@ -218,7 +218,7 @@ const syncPill: CSSProperties = {
   display: "flex",
   alignItems: "center",
   gap: theme.space(2),
-  padding: "4px 10px",
+  padding: `${theme.space(1)} ${theme.space(2)}`,
   borderRadius: theme.radius.md,
   background: theme.color.accent,
   color: theme.color.accentContrast,
@@ -258,7 +258,7 @@ const detailsButton: CSSProperties = {
   display: "inline-flex",
   alignItems: "center",
   gap: 4,
-  padding: `2px ${theme.space(2)}`,
+  padding: `${theme.space(1)} ${theme.space(2)}`,
   border: "none",
   borderRadius: theme.radius.sm,
   background: "transparent",
@@ -300,7 +300,7 @@ const errorCard: CSSProperties = {
 
 const errorTitle: CSSProperties = {
   margin: 0,
-  fontSize: 13,
+  ...theme.type.base,
   fontWeight: 600,
   color: theme.color.danger,
 };
@@ -319,7 +319,7 @@ const retryButton: CSSProperties = {
   background: theme.color.accent,
   color: theme.color.accentContrast,
   fontFamily: theme.font.ui,
-  fontSize: 13,
+  ...theme.type.base,
   fontWeight: 600,
   cursor: "pointer",
 };
diff --git a/runner/packages/editor-shell/src/SideNav.tsx b/runner/packages/editor-shell/src/SideNav.tsx
index abda4084e..b52daa068 100644
--- a/runner/packages/editor-shell/src/SideNav.tsx
+++ b/runner/packages/editor-shell/src/SideNav.tsx
@@ -101,7 +101,7 @@ export const SIDE_NAV_WIDTH = 320;
 const sideNav: CSSProperties = {
   display: "flex",
   flexDirection: "column",
-  gap: 2,
+  gap: theme.space(1),
   padding: theme.space(2),
   borderRight: `1px solid ${theme.color.border}`,
   background: theme.color.surfaceSunken,
@@ -118,7 +118,7 @@ const navRow: CSSProperties = {
   borderRadius: theme.radius.md,
   color: theme.color.text,
   fontFamily: theme.font.ui,
-  fontSize: 13,
+  ...theme.type.base,
   textAlign: "left",
   textDecoration: "none",
   cursor: "pointer",
@@ -130,7 +130,7 @@ const subNav: CSSProperties = {
   gap: 1,
   // Aligned under the parent row's label, not its icon, so the indent reads as
   // "inside Guide" rather than as a second column.
-  margin: `2px 0 ${theme.space(1)} ${theme.space(6)}`,
+  margin: `${theme.space(1)} 0 ${theme.space(1)} ${theme.space(6)}`,
   paddingLeft: theme.space(3),
   borderLeft: `1px solid ${theme.color.border}`,
 };
@@ -146,7 +146,7 @@ const subRow = (active: boolean): CSSProperties => ({
   // exists at all.
   color: active ? theme.color.accentText : theme.color.textMuted,
   fontFamily: theme.font.ui,
-  fontSize: 12.5,
+  ...theme.type.base,
   textDecoration: "none",
   // No `background` when inactive: `.hot-menu-row`'s hover lives in the app's
   // stylesheet and an inline value would outrank it (ADR-0026).
diff --git a/runner/packages/editor-shell/src/TopBar.tsx b/runner/packages/editor-shell/src/TopBar.tsx
index a8e194135..161771ae3 100644
--- a/runner/packages/editor-shell/src/TopBar.tsx
+++ b/runner/packages/editor-shell/src/TopBar.tsx
@@ -125,8 +125,6 @@ export function TopBar({
         </button>
       )}
 
-      <ThemeToggle />
-
       {/* Download is gated on having files, not on auth. The design's top-right is
           "Download (authed) / Sign in (anon)" — `72:15697` draws `Sign in` alone —
           but Download has always worked for anonymous visitors, so ADR-0023 rule 1
@@ -154,6 +152,11 @@ export function TopBar({
         </button>
       )}
 
+      {/* After Download, before the avatar: display preference, not a workspace
+          action, so it sits at the passive end of the bar rather than between
+          Fork/Save and Download. */}
+      <ThemeToggle />
+
       {/* Sign in used to sit here, beside Download (`72:15697`). It moved to the
           preview status bar in DEV-2505: signing in is `@handsontable.com`-only
           and internal, while most visitors to this page are external (a client on
@@ -195,7 +198,7 @@ const actionButton: React.CSSProperties = {
   background: "transparent",
   color: theme.color.text,
   fontFamily: theme.font.ui,
-  fontSize: 13,
+  ...theme.type.base,
   fontWeight: 600,
   cursor: "pointer",
   whiteSpace: "nowrap",
diff --git a/runner/packages/editor-shell/src/icons/ui.tsx b/runner/packages/editor-shell/src/icons/ui.tsx
index 148d41080..02ce8688d 100644
--- a/runner/packages/editor-shell/src/icons/ui.tsx
+++ b/runner/packages/editor-shell/src/icons/ui.tsx
@@ -57,6 +57,7 @@ import {
   IconBook as TablerBook,
   IconBrandGithub as TablerBrandGithub,
   IconBrandReactNative as TablerBrandReactNative,
+  IconArrowUp as TablerArrowUp,
   IconChartBar as TablerChartBar,
   IconChevronDown as TablerChevronDown,
   IconChevronLeft as TablerChevronLeft,
@@ -68,6 +69,7 @@ import {
   IconDownload as TablerDownload,
   IconExternalLink as TablerExternalLink,
   IconFolderPlus as TablerFolderPlus,
+  IconInfoCircle as TablerInfoCircle,
   IconLayoutSidebarLeftCollapse as TablerLayoutSidebarLeftCollapse,
   IconLayoutSidebarLeftExpand as TablerLayoutSidebarLeftExpand,
   IconListDetails as TablerListDetails,
@@ -108,6 +110,9 @@ function ui(displayName: string, Base: TablerIcon) {
 export const IconBook = ui("IconBook", TablerBook);
 export const IconBrandGithub = ui("IconBrandGithub", TablerBrandGithub);
 export const IconBrandReactNative = ui("IconBrandReactNative", TablerBrandReactNative);
+// The chat composer's send glyph (DEV-2047 restyle) — the docs assistant sends
+// with ↑, and the two assistants should read as one product.
+export const IconArrowUp = ui("IconArrowUp", TablerArrowUp);
 export const IconChartBar = ui("IconChartBar", TablerChartBar);
 export const IconChevronDown = ui("IconChevronDown", TablerChevronDown);
 export const IconChevronLeft = ui("IconChevronLeft", TablerChevronLeft);
@@ -119,6 +124,9 @@ export const IconDotsVertical = ui("IconDotsVertical", TablerDotsVertical);
 export const IconDownload = ui("IconDownload", TablerDownload);
 export const IconExternalLink = ui("IconExternalLink", TablerExternalLink);
 export const IconFolderPlus = ui("IconFolderPlus", TablerFolderPlus);
+// The Style panel's per-token info mark (Theme Builder's row treatment): the
+// token description moved off the row into a tooltip behind this.
+export const IconInfoCircle = ui("IconInfoCircle", TablerInfoCircle);
 export const IconLayoutSidebarLeftCollapse = ui(
   "IconLayoutSidebarLeftCollapse",
   TablerLayoutSidebarLeftCollapse,
diff --git a/runner/packages/editor-shell/src/styles.ts b/runner/packages/editor-shell/src/styles.ts
index b9aa1de7d..a7707a690 100644
--- a/runner/packages/editor-shell/src/styles.ts
+++ b/runner/packages/editor-shell/src/styles.ts
@@ -104,14 +104,14 @@ export const s = {
     background: t.color.surface,
     color: t.color.text,
     fontFamily: t.font.ui,
-    fontSize: 13,
+    ...t.type.base,
   }),
 
   /** The pill's text. Every call site drew its own identical copy of this — the
    *  editor's, My Demos', and now Settings' — so it lives here once. */
   pillLabel: {
     fontFamily: t.font.ui,
-    fontSize: 13,
+    ...t.type.base,
     fontWeight: 500,
     color: t.color.text,
   } satisfies CSSProperties,
@@ -137,7 +137,7 @@ export const s = {
     borderBottom: `1px solid ${t.color.border}`,
     background: t.color.surface,
     fontFamily: t.font.ui,
-    fontSize: 13,
+    ...t.type.base,
     color: t.color.text,
   } satisfies CSSProperties,
 
@@ -173,7 +173,7 @@ export const s = {
     background: t.color.surfaceSunken,
     boxShadow: `inset 0 -1px 0 ${t.color.border}`,
     fontFamily: t.font.ui,
-    fontSize: 13,
+    ...t.type.base,
     color: t.color.text,
   } satisfies CSSProperties,
 
@@ -190,7 +190,7 @@ export const s = {
     background: "transparent",
     color: t.color.textMuted,
     fontFamily: t.font.ui,
-    fontSize: 13,
+    ...t.type.base,
     textAlign: "left",
     cursor: "pointer",
   } satisfies CSSProperties,
@@ -206,7 +206,7 @@ export const s = {
     background: "transparent",
     color: t.color.text,
     fontFamily: t.font.ui,
-    fontSize: 13,
+    ...t.type.base,
     cursor: "pointer",
     whiteSpace: "nowrap",
   } satisfies CSSProperties,
@@ -235,9 +235,9 @@ export const s = {
     background: active ? t.color.accentSoft : "transparent",
     color: active ? t.color.text : t.color.textMuted,
     fontFamily: t.font.ui,
-    fontSize: 13,
+    ...t.type.base,
     fontWeight: active ? 600 : 400,
-    padding: `6px ${t.space(2)}`,
+    padding: `${t.space(1)} ${t.space(2)}`,
     cursor: "pointer",
     whiteSpace: "nowrap",
   }),
@@ -372,7 +372,7 @@ export const s = {
     padding: t.space(4),
     textAlign: "center",
     fontFamily: t.font.ui,
-    fontSize: 13,
+    ...t.type.base,
     color: t.color.textMuted,
   } satisfies CSSProperties,
 
@@ -424,8 +424,8 @@ export const s = {
 
   select: {
     fontFamily: t.font.mono,
-    fontSize: 13,
-    padding: `5px 8px`,
+    ...t.type.base,
+    padding: `${t.space(1)} ${t.space(2)}`,
     borderRadius: t.radius.md,
     border: `1px solid ${t.color.border}`,
     background: t.color.surface,
diff --git a/runner/packages/editor-shell/src/theme.ts b/runner/packages/editor-shell/src/theme.ts
index 4fe06f517..5d91c26c6 100644
--- a/runner/packages/editor-shell/src/theme.ts
+++ b/runner/packages/editor-shell/src/theme.ts
@@ -68,7 +68,10 @@ const LIGHT_COLORS = {
   controlBorder: "#e7e7e9", // horizon/palette/100
   text: "#262624", // horizon/palette/700
   textMuted: "#727272",
-  hover: "rgba(120, 130, 150, 0.16)", // neutral row/button rollover
+  // Neutral row/button rollover. 0.10, down from 0.16: on white surfaces the
+  // old value read as a selection rather than a hover — most visibly on the
+  // Style panel's rows and its tab strip.
+  hover: "rgba(120, 130, 150, 0.1)",
 
   // Panes that wrap third-party surfaces. `editorBg` sits behind CodeMirror,
   // `previewBg` behind the demo iframe — both must track the shell, because
@@ -165,7 +168,24 @@ export const theme = {
   shadow: refs("shadow", LIGHT_SHADOWS),
   font: {
     ui: `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif`,
-    mono: `"JetBrains Mono", "SFMono-Regular", ui-monospace, Menlo, Consolas, monospace`,
+    mono: `"Fira Code", "JetBrains Mono", "SFMono-Regular", ui-monospace, Menlo, Consolas, monospace`,
+  },
+  /** The design's whole type scale, read off frame `48:6560` — two sizes, four
+   *  roles. Every text in the frame is one of these; nothing is 13px, and
+   *  hierarchy is carried by colour and tracking, not extra sizes. Spread one of
+   *  these into a style object rather than writing `fontSize` by hand — the 13px
+   *  the shell shipped with was exactly the kind of drift this exists to stop.
+   *   - `base`  12/20: primary UI text — pills, tabs, buttons, body copy (48:6583)
+   *   - `small` 10/20: secondary lines — descriptions, status bar (48:6758, 48:6742)
+   *   - `row`   12/16: dense tree rows — files, dependency URLs. The frame draws
+   *     these at 10 (72:16918); raised to 12 by decision — 10px file names were
+   *     too small to read — with the 16px line kept so the 24px rows stay 24.
+   *   - `label` 10/20 +0.8px: uppercase section headers (48:6752) */
+  type: {
+    base: { fontSize: 12, lineHeight: "20px" },
+    small: { fontSize: 10, lineHeight: "20px" },
+    row: { fontSize: 12, lineHeight: "16px" },
+    label: { fontSize: 10, lineHeight: "20px", letterSpacing: "0.8px" },
   },
   radius: { sm: "4px", md: "8px", lg: "12px" },
   space: (n: number) => `${n * 4}px`,
@@ -206,20 +226,33 @@ const KEYFRAMES = `@keyframes hot-spin{to{transform:rotate(360deg)}}`;
 export const THEME_CSS = [
   block(":root", "light", LIGHT_COLORS, LIGHT_SHADOWS),
   block(`:root[${THEME_ATTR}="dark"]`, "dark", DARK_COLORS, DARK_SHADOWS),
+  // The font stacks as variables, for the same reason the colours are: component
+  // stylesheets (the app's `panels.css`, the shell's `installCss` strings) have no
+  // way to reach the TS constants, and a stack pasted into CSS drifts.
+  `:root{--hot-font-ui:${theme.font.ui};--hot-font-mono:${theme.font.mono}}`,
   KEYFRAMES,
 ].join("\n");
 
 const STYLE_ID = "hot-theme-vars";
 
-/** Inject `THEME_CSS` once. Called at module scope below, so the variables exist
- *  before React's first paint regardless of which module pulled `theme.ts` in. */
-export function installThemeCss(): void {
+/** Inject a stylesheet once, keyed by id. The shell can't import `.css` files —
+ *  it ships as source and typechecks standalone — so components that need real
+ *  selectors (pseudo-elements, hover, attribute states) register a CSS string at
+ *  module scope with this instead. Values in those strings must be `var(--hot-…)`
+ *  references, never literals: the mode flip works by swapping variables. */
+export function installCss(id: string, css: string): void {
   if (typeof document === "undefined") return;
-  if (document.getElementById(STYLE_ID)) return;
+  if (document.getElementById(id)) return;
   const el = document.createElement("style");
-  el.id = STYLE_ID;
-  el.textContent = THEME_CSS;
+  el.id = id;
+  el.textContent = css;
   document.head.appendChild(el);
 }
 
+/** Inject `THEME_CSS` once. Called at module scope below, so the variables exist
+ *  before React's first paint regardless of which module pulled `theme.ts` in. */
+export function installThemeCss(): void {
+  installCss(STYLE_ID, THEME_CSS);
+}
+
 installThemeCss();
diff --git a/runner/pnpm-lock.yaml b/runner/pnpm-lock.yaml
index 5eb8b0012..d262c94e4 100644
--- a/runner/pnpm-lock.yaml
+++ b/runner/pnpm-lock.yaml
@@ -26,6 +26,9 @@ importers:
 
   apps/authoring:
     dependencies:
+      '@fontsource/fira-code':
+        specifier: ^5.3.0
+        version: 5.3.0
       '@handsontable/demo-editor-shell':
         specifier: workspace:*
         version: link:../../packages/editor-shell
@@ -825,6 +828,9 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@fontsource/fira-code@5.3.0':
+    resolution: {integrity: sha512-EJL968RJRkakubAj/coU8pSUaeTE5UNoRjtzAr6kGiSZ3jWuN8/AKWHwym/PFUaQL1q7IL/H+EXs4358YhrTBQ==}
+
   '@img/colour@1.1.0':
     resolution: {integrity: sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==}
     engines: {node: '>=18'}
@@ -2427,6 +2433,8 @@ snapshots:
   '@esbuild/win32-x64@0.28.1':
     optional: true
 
+  '@fontsource/fira-code@5.3.0': {}
+
   '@img/colour@1.1.0': {}
 
   '@img/sharp-darwin-arm64@0.34.5':