Database governance built for humans and agents — controlling changes and access across every major database.
SQL Editor Theme Pattern — Design
Date: 2026-06-09 Status: Implemented — the sections below are the original design; the box immediately below records what actually shipped and where it diverged. Scope: SQL Editor only (UI chrome + Monaco editor surface + result views)
Implementation notes — as shipped (supersedes design details below)
The data-driven model, the SQLEditorThemeScope, the workspace-scoped localStorage
preference, and the ThemeSelect toolbar switcher all landed as designed. The
following diverged during implementation (driven by how the codingame VSCode Monaco
runtime and the real DOM behave):
- Catalog:
light,dark, andsolarized-dark. Solarized Dark shipped as the first named theme; the other originally-planned named themes (Solarized Light, Monokai, Nord) were not authored. - The Monaco
editor/syntaxtheme layer was removed entirely. This app runs Monaco through the codingame VSCode theme service, which ignoresmonaco.editor.defineTheme, so per-theme editor colors and syntax palettes never reach the canvas. TheSQLEditorTheme.editor/.syntaxfields and theEditorChromeColors/SyntaxPalettetypes are deleted;buildMonacoThemenow carries only thevs/vs-darkbase + the word-highlight reset. A theme is just{ id, name, monacoBase, tokens }. (Authentic per-theme editor syntax would require registering real VSCode themes — a documented follow-up; see Future work.) - Editor background follows the chrome via a transparent canvas. Because the canvas
can't be themed through
defineTheme, a scoped CSS rule makes the Monaco editor (.sqleditor--wrapper .monaco-editor+-background+.margin) transparent so it shows the chrome--color-background; syntax token colors come from thevs/vs-darkbase. Transparent (not an opaque token) so Monaco's own overlays (current line, selection) still composite on top.- Portaled editors opt in via a marker class. The rule's primary selector is
.sqleditor--wrapper-scoped, so a SQL-EditorMonacoEditorthat portals outside that subtree (the access-request drawer's editor, mounted in the overlay root) would otherwise keep the opaquevs/vs-darkcanvas and mismatch a named theme's chrome bg (e.g. Solarized Dark's teal). Such editors add thesqleditor--monaco-transparentmarker class (a second selector on the same rule) plusbg-background, so the canvas shows the active theme's--color-background— consistent with the worksheet editor.
- Portaled editors opt in via a marker class. The rule's primary selector is
- Theme names are literal labels; the switcher is dev-only.
ThemeSelectis gated behindisDev()(hidden in production), so theme names aren't translated:SQLEditorTheme.nameis a plain display string (no i18n key) — built-ins, proper-noun presets (Solarized Dark), and future user-named custom themes all just set it. - Monaco theming is per-editor + a change-only controller, not a mount-time global
setTheme. Callingmonaco.editor.setThemewhile an editor is still constructing races the codingame theme service and throws → the editor falls back to a read-only<pre>. So: each SQL-Editor editor passesoptions.theme(themes at construction), anduseMonacoThemeControllerre-applies the global theme only on a genuine theme change (StrictMode-safe via a prev-value ref), never on mount. getResolvedThemefalls back to each theme's base (vs/vs-dark). Custombb-*themes do not register in this runtime (the service silently swallowsdefineTheme), so a dark theme used to fall back to the lightvs— leaving the editor light under Dark.core.tsrecords each preset'smonacoBaseand falls back to it.- Chrome theming was a transparent-container problem, not hardcoded colors. The
big panels already use semantic tokens; they're just transparent / un-classed, so on
the white default they looked fine and under Dark showed white. Fixes:
bg-backgroundtext-mainon thesqleditor--wrapper(themed backdrop + default text), and the global default border now usesrgb(var(--color-block-border))(identical to the old gray-200 in light, themed inside a scope). The active-statement decoration was tokenized (bg-control-bg-hover). Only a handful of genuinely-hardcoded colors needed migrating.
- Portaled overlays are themed at the overlay layer root, not per component.
Dialogs (Save Sheet, …), the access drawer, and Base-UI Select/Popover/Tooltip popups
all portal to the app-global overlay root, outside the scope's DOM — CSS vars can't
cascade.
useSQLEditorOverlayThemesets the theme's vars + a default text color ongetLayerRoot("overlay")while the SQL Editor is mounted (reverted on unmount), which themes all of them from one place. (In light the vars equal:root, so it's a no-op outside a dark theme.) - Admin (terminal) nested scope, drawer chrome, and the
dark-prop removal landed as designed. isDarkis fully deprecated — no light/dark branching in components. The original design exposedSQLEditorTheme.isDark"for the few spots that need a boolean," but in practice components usedisDark ? colorA : colorB, which bakes colors into the component and can't extend to a 3rd/custom theme. So: the property is removed fromSQLEditorTheme; allisDark ? colorA : colorBbecame plain semantic-token classes (each theme defines the value);resolveAdminThemekeys offmonacoBase === "vs-dark"; and the one genuine terminal-vs-worksheet layout difference uses an explicitcompactprop (TerminalPanel→ResultView→SingleResultView), not the theme. Net: colors are 100% token-driven and a custom theme is just another token map.- Native controls follow
color-scheme, not the tokens. Browser/OS-drawn controls —<input type="datetime-local">calendar popups, scrollbars, native<select>popups — ignore our--color-*tokens entirely. The only lever is the CSScolor-schemeproperty, so every theme-application site sets it from athemeColorScheme(theme)helper (vs-dark → "dark"):SQLEditorThemeScope(editor body, terminal), the request drawers' inlineSheetContentstyle, and the overlay layer root. Without it a dark theme would show a white native date picker over the dark drawer.
Net new files vs. the design: theme/useSQLEditorOverlayTheme.ts. The getResolvedTheme
base-fallback is unit-tested in monaco/core.test.ts.
Goal
Extract the colors the SQL Editor uses today into a data-driven theme model and
add a runtime preset switcher scoped to the SQL Editor. The current look becomes
the light preset (zero visual change as the default); a dark preset plus several
named pre-defined themes ship alongside it. The model is shaped so that user-defined
custom themes can be added later with no re-architecture — a custom theme is just
another theme object.
Shipped reality: the catalog ships three themes (
light,dark,solarized-dark); the Monacoeditor/syntaxlayer andisDarkwere removed; and themenameis a plain literal label (no i18n). The detailededitor/syntax/ six-theme architecture in §1–§6 below is the original design — see Implementation notes — as shipped above, which is authoritative wherever it conflicts.
This phase ships a small catalog of pre-defined preset themes (below). Custom-theme editing UI, a "System" option, and backend persistence are explicitly out of scope (see Future work).
Theme catalog
| id | name | monacoBase | notes |
|---|---|---|---|
light |
Default Light | vs |
today's :root/bb look, verbatim — the default |
dark |
Default Dark | vs-dark |
Bytebase dark, inherits vs-dark editor + chrome tokens |
solarized-dark |
Solarized Dark | vs-dark |
first named theme; chrome only (editor stays vs-dark base) |
Locked decisions
| Decision | Choice |
|---|---|
| End goal | Build the foundation for runtime-switchable themes |
| Scope | SQL Editor only — chrome + Monaco + result views |
| Granularity | Preset themes only — light, dark, solarized-dark shipped (catalog above) |
| Syntax fidelity | Chrome only. The codingame Monaco runtime ignores per-theme defineTheme colors, so editor syntax stays the vs/vs-dark base; the editor background follows the chrome via a transparent canvas. (Per-theme syntax would need real VSCode themes — see Future work.) |
| Token scoping | Scoped override — re-declare --color-* on the SQL Editor container |
| Persistence | localStorage, client-only, workspace-scoped |
| Theme representation | Approach A — theme is a plain JS token map; both layers derive from it |
| Admin (terminal) mode | A nested theme scope; effective theme = selected.monacoBase === "vs-dark" ? selected : dark |
Why Approach A (data-driven) over a static CSS-class model
A theme is data: a { token: "r g b" } object. The chrome consumes it by writing
the tokens as inline CSS custom properties on the container; Monaco consumes it via a
theme generated from the same object. Presets and (future) custom themes are the
same shape and the same code path — custom is just an object we did not ship. A static
model (a .sqle-theme-dark CSS class + a hand-authored Monaco theme file) cannot
represent values unknown at build time, so custom themes would force re-introducing
the data-driven mechanism anyway, on top of two diverging sources of truth.
Current state (as found)
- Tokens. Semantic CSS variables live at
:rootinfrontend/src/assets/css/tailwind.css(--color-control*,--color-accent*,--color-main*, status colors,--color-block-border,--color-background,--color-dark-bg,--color-matrix-green*). Tailwind utilities resolve torgb(var(--color-x) / <alpha-value>)(frontend/tailwind.config.js), so overriding a variable on a parent element cascades to all descendants. This is the mechanism the whole design relies on. - Monaco. Two themes (
bblight,bb-dark) are defined once infrontend/src/react/components/monaco/core.tsviainitializeTheme(); they read CSS vars from:rootthroughcallCssVariable().monaco.editor.setTheme()is global and is currently called once per editor at construction (MonacoEditor.tsx:346). The admin terminal usesvs-darkintentionally. - Settings store.
useSQLEditorEditorStore(Zustand) infrontend/src/react/stores/sqlEditor/editor.tsalready persists prefs to localStorage viasafeRead/safeWrite, workspace-scoped throughfrontend/src/utils/storage-keys.ts. - Root container.
<div className="sqleditor--wrapper …">inSQLEditorHomePage.tsx:187wraps the editor body, but not everything: portaled overlays (FAB/sidebar →getLayerRoot("overlay")) andRequestDrawerHost(SQLEditorLayout.tsx:62, a sibling above the wrapper) render outside it. The scoped CSS-variable attach point is therefore the layout (SQLEditorLayout), with per-portal re-application (see Architecture §4 → Portals & sibling hosts). - Admin (terminal) mode is a nested dark subtree, not whole-editor dark. A tab's
mode("WORKSHEET"|"ADMIN", in the tab store) drivesPanels.tsx:162to swap the code panel betweenStandardPanelandTerminalPanel. Only<TerminalPanel>(outermost<div class="… bg-dark-bg">atTerminalPanel.tsx:206) goes dark — itsEditorAction,CompactSQLEditor(Monacovs-dark,CompactSQLEditor.tsx:323), andResultView(darkprop hardcodedtrue,TerminalPanel.tsx:236). The surrounding chrome (tabs, schema pane, connection pane) stays light. This subtree is the natural nested scope boundary for the theme system. - Hardcoded colors. Many SQL Editor components bypass the tokens with raw
palette classes (
bg-gray-200,border-zinc-500),dark:-prefixed variants, and inlinergb()/hex. These must be migrated for scoped theming to work end-to-end (full inventory in Color migration).
Architecture
1. Theme token model
A theme has two layers: the chrome layer (CSS-variable token map that re-themes
the SQL Editor UI) and the Monaco layer (editor-surface colors + syntax palette
that the chrome --color-* set does not cover). A named theme like Monokai is defined
largely by its Monaco layer.
// frontend/src/react/components/sql-editor/theme/types.ts
type RGB = string; // "r g b" for chrome tokens, e.g. "82 82 91"
type Hex = string; // "#rrggbb" for Monaco (Monaco consumes hex)
interface SQLEditorTheme {
id: string; // "light" | "dark" | … (stable, persisted)
name: string; // i18n key for the display label
// NOTE: `isDark` was REMOVED before merge (see Implementation notes). Components
// never branch on a boolean; light/dark differences are encoded in `tokens`, and
// the one place that needs the Monaco family reads `monacoBase` directly.
monacoBase: "vs" | "vs-dark";
tokens: Record<SQLEditorThemeToken, RGB>; // chrome layer
editor: Partial<EditorChromeColors>; // Monaco surface (bg, gutter, selection, cursor, lineHighlight, …)
syntax?: SyntaxPalette; // Monaco token colors; omitted → inherit monacoBase verbatim
}
tokens— the SQL-Editor subset of the existing--color-*names (control*, accent*, main*, background, block-border, link-hover, status colors, matrix-green*, dark-bg). Names are unchanged; we only override values per theme, so existingtext-control/bg-control-bgclasses keep working.editor— Monacocolors{}entries:editor.background,editorGutter.*,editor.selectionBackground,editorCursor.foreground,editorLineNumber.foreground/activeForeground, line-highlight, etc.syntax— a normalized palette (comment,keyword,string,number,type,function,variable,operator,delimiter,predefined) thatbuildMonacoThememaps onto Monaco token rules (incl. SQL scopes likepredefined.sql,operator.sql,string.sql). Definingsyntaxonce per theme, language-agnostic, keeps each preset to a single small palette rather than per-grammar rule lists.
Supporting types (the keys each layer must fill — validateTheme enforces them):
// chrome layer — the SQL-Editor subset of existing --color-* names
type SQLEditorThemeToken =
| "--color-control" | "--color-control-hover"
| "--color-control-light" | "--color-control-light-hover"
| "--color-control-bg" | "--color-control-bg-hover"
| "--color-control-placeholder" | "--color-control-border"
| "--color-accent" | "--color-accent-hover" | "--color-accent-disabled" | "--color-accent-text"
| "--color-main" | "--color-main-hover" | "--color-main-text"
| "--color-background" | "--color-block-border" | "--color-link-hover"
| "--color-info" | "--color-info-hover" | "--color-warning" | "--color-warning-hover"
| "--color-error" | "--color-error-hover" | "--color-success" | "--color-success-hover"
| "--color-matrix-green" | "--color-matrix-green-hover" | "--color-dark-bg";
// Monaco surface (canvas — not reachable by CSS vars)
interface EditorChromeColors {
background: Hex; selectionBackground: Hex; cursor: Hex; lineHighlight: Hex;
gutterBackground: Hex; lineNumber: Hex; activeLineNumber: Hex;
}
// Monaco token colors, normalized & language-agnostic
interface SyntaxPalette {
comment: Hex; keyword: Hex; string: Hex; number: Hex; type: Hex;
function: Hex; variable: Hex; operator: Hex; delimiter: Hex; predefined: Hex;
}
Derivation functions — the single SQLEditorTheme object is the source; both layers
are computed from it (this is the whole point of Approach A: presets and future custom
themes flow through the exact same functions):
// theme/derive.ts
// CHROME: tokens → inline CSS custom properties, spread onto a container's `style` prop.
// { "--color-control": "82 82 91", … } → <div style={vars}>
function themeToCssVars(tokens: SQLEditorTheme["tokens"]): CSSProperties;
// MONACO: whole theme → registered standalone theme data.
// maps `editor` → IStandaloneThemeData.colors, `syntax` → .rules (incl. SQL scopes).
function buildMonacoTheme(theme: SQLEditorTheme): monaco.editor.IStandaloneThemeData;
// MONACO name used by defineTheme(name, …) and the global setTheme controller.
function monacoThemeName(theme: SQLEditorTheme): string; // `bb-${theme.id}`
// ADMIN: foreground-panel resolution for the nested terminal scope + Monaco controller.
function resolveAdminTheme(selected: SQLEditorTheme): SQLEditorTheme; // selected.monacoBase === "vs-dark" ? selected : presets.dark
// VALIDATION: throws if any chrome token / editor key / syntax key is missing.
// Unit-tested across every entry in PRESETS so no theme can ship with holes.
function validateTheme(theme: SQLEditorTheme): void;
<SQLEditorThemeScope> (§4) is the only consumer of themeToCssVars (for the chrome) and
context; monaco/core.ts calls buildMonacoTheme once per preset at init, and the single
Monaco controller (§4 → Monaco) is the only caller of setTheme(monacoThemeName(active)).
2. Presets
One file per theme under frontend/src/react/components/sql-editor/theme/presets/
(light.ts, dark.ts, solarized-light.ts, solarized-dark.ts, monokai.ts,
nord.ts), re-exported from an index.ts as an ordered PRESETS array. One file per
theme keeps each palette small and reviewable, and makes adding a theme a single new
file.
light—tokenscopied verbatim from today's:root;editor/syntaxreproduce the currentbblook so the default render is byte-for-byte identical to current.monacoBase: "vs".dark— derived from existingdark:choices (gray-700/800,zinc-500/600,--color-dark-bg) andbb-dark. Starting chrome palette below; tunable, final values confirmed visually during implementation.Token Light (current) Dark (proposed start) --color-background255 255 25530 30 30(dark-bg)--color-control-bg243 244 24655 65 81(gray-700)--color-control-bg-hover229 231 23575 85 99(gray-600)--color-control82 82 91229 231 235(gray-200)--color-control-light113 113 122209 213 219(gray-300)--color-control-placeholder161 161 170156 163 175(gray-400)--color-control-border209 213 219113 113 122(zinc-500)--color-block-border229 231 23582 82 91(zinc-600)--color-main24 24 27244 244 245--color-accent79 70 229129 140 248(indigo-400)status colors unchanged hue, may lighten slightly for contrast on dark bg solarized-light/solarized-dark/monokai/nord— authored from each theme's published palette. Each derives its chrometokensfrom its base/bg and accent colors (so the SQL Editor UI matches), plus its authenticeditorandsyntaxvalues. Reference palettes:- Solarized: base03–base3 + accent set (yellow/orange/red/magenta/violet/blue/cyan/green)
- Monokai: bg
#272822, fg#f8f8f2, green#a6e22e, pink#f92672, orange#fd971f, blue#66d9ef, comment#75715e - Nord: Polar Night
#2e3440…#4c566a, Snow Storm#d8dee9…#eceff4, Frost#8fbcbb/#88c0d0/#81a1c1/#5e81ac, Aurora accents
Each theme must define every required chrome token (no holes) so it renders coherently; a
validateTheme()helper + a unit test enforce completeness across the whole catalog.
3. Store & persistence
Extend useSQLEditorEditorStore:
- State:
themeId: string(default"light"). - Action:
setThemeId(id). - Persistence: read on init / write on change via the existing
safeRead/safeWrite- a new workspace-scoped key in
storage-keys.ts, e.g.storageKeySqlEditorTheme(scope)→bb.sql-editor.theme[.${workspaceId}], matching the current scoping scheme. Unknown/invalid persisted id falls back to"light".
- a new workspace-scoped key in
No backend or proto changes.
4. Applying the theme — context + nested scopes
Theming flows through a small React context so a subtree can override the active theme (this is what makes admin mode compose cleanly):
const SQLEditorThemeContext = createContext<SQLEditorTheme>(/* light */);
const useSQLEditorTheme = () => useContext(SQLEditorThemeContext);
A <SQLEditorThemeScope theme={…}> component does two things for whatever it wraps:
- provides the theme via context (so descendants can read
theme.monacoBase/ the Monaco theme name), and - applies the theme's
tokensas inline CSS custom properties on its container element. Because every SQL Editor component uses the semantic Tailwind classes, the subtree re-themes via CSS cascade.
Root scope. Wrap the SQL Editor at the layout level — SQLEditorLayout,
around both the route content (SQLEditorRouteShell → SQLEditorHomePage) and
RequestDrawerHost (SQLEditorLayout.tsx:62) — in a SQLEditorThemeScope whose theme
is the selected preset (from useSQLEditorEditorStore.themeId). The rest of Bytebase
keeps the global :root values; only the SQL Editor subtree is re-themed. (An earlier
draft scoped only .sqleditor--wrapper; that misses SQL-Editor UI rendered outside that
subtree — see Portals & sibling hosts below.)
Portals & sibling hosts. Scoped CSS variables re-theme via DOM cascade, but
React portals mount their DOM elsewhere: React context still propagates through a
portal, CSS custom properties do not. Several SQL-Editor surfaces render outside the
chrome DOM subtree and would otherwise keep the global (light) :root tokens under a
dark/named theme:
SQLEditorHomePageportals the mobile FAB and the sidebar overlay togetLayerRoot("overlay")(SQLEditorHomePage.tsx:160-182, 191-208).AccessGrantRequestDrawer(rendered byRequestDrawerHost,RequestDrawerHost.tsx:74) is aSheetthat portals to the overlay layer and hosts its ownMonacoEditor(AccessGrantRequestDrawer.tsx:262).
The layer roots are app-global (shared with the rest of Bytebase), so we cannot wrap
them in a SQL-Editor-only scope. Instead, each portaled SQL-Editor surface re-applies the
chrome theme on its own container: wrap the portal's children in a nested
SQLEditorThemeScope whose theme comes from useSQLEditorTheme() (read through the
context that the portal preserves) so it re-writes the --color-* vars onto the portaled
DOM. For the request drawer this re-themes its Sheet chrome (form controls, labels).
Its embedded Monaco, however, cannot have its own theme — Monaco's theme is global
(see Monaco below); the drawer's editor shares the one active Monaco theme. No new
global chrome theming — only the specific SQL-Editor portal subtrees re-apply vars.
Portal coverage for v1 (scope decision). The portal inventory is larger than the
FAB/sidebar + drawer: other SQL-Editor surfaces also mount under the app-global overlay
root — the custom hover panels (DatabaseHoverPanel, SchemaPane/HoverPanel), the
RequestRoleSheet (same RequestDrawerHost path), and Base-UI-internal popups
(ConnectChooser's Select dropdown, EllipsisCell's tooltip). For the first ship we
wrap our own createPortal/Sheet surfaces (overlays, drawer, RequestRoleSheet,
hover panels) in a nested scope. The Base-UI-internal popups portal through shared ui/*
primitives and can't be re-scoped per-SQL-Editor without touching app-wide components, so
they are a tracked follow-up — under a dark/named theme they may briefly show the
default (light) tokens. Visual tests (§ Testing) enumerate covered vs deferred surfaces.
(If app-scope chrome lands later, the whole portal problem disappears: tokens applied at
app root cascade into the shared overlay root automatically.)
As shipped — superseded by the overlay-root approach. Rather than wrapping each portal in its own nested scope,
useSQLEditorOverlayThemethemes the shared overlay layer root once with the active theme (so it also covers the Base-UI-internal popups that couldn't be re-scoped individually — they're no longer a follow-up). Two consequences for the surfaces above:
RequestRoleSheetis theme-injected by its host via an explicit prop. It's shared with non-SQL-Editor pages (MembersPage,ComponentPermissionGuard), so it must NOT read the active theme itself (leaks the SQL-Editor theme onto those pages) and must NOT read the shared theme context (any ambientSQLEditorThemeScopeancestor would bleed in). Instead it takes an optionalthemeprop and applies it as inline vars on itsSheetContent(the Sheet portals to the overlay root, so inline-on-content is what reaches the portaled DOM). Only the SQL-Editor host (RequestDrawerHost) passes it — the active theme. With no prop,SheetContentis left unstyled and inherits:root, so the drawer always renders in the default light app theme outside the SQL Editor, regardless of any ambient scope.AccessGrantRequestDrawerkeeps an explicit nested scope + inlinesheetStyle, both keyed off the active theme (it's SQL-Editor-only, so that's safe and also themes its embedded Monaco). Its Monaco additionally opts into the transparent-canvas rule via thesqleditor--monaco-transparentmarker class.
Nested admin scope. Wrap <TerminalPanel>'s root div (TerminalPanel.tsx:206) in a
nested SQLEditorThemeScope whose theme is the resolved admin theme:
resolveAdminTheme(selected) = selected.monacoBase === "vs-dark" ? selected : presets.dark;
Its inline CSS-var overrides win over the parent scope for the terminal subtree (CSS
cascade), so the terminal + its ResultViews render dark (or in the selected dark
theme), while the surrounding chrome keeps the selected theme. Worksheet mode renders
under the root scope only — no nesting.
This is the replacement for the dark boolean prop: ResultView reads nothing —
its styling comes entirely from the scope's tokens rather than dark: variants or a
boolean. (As shipped, ResultView keeps only a compact prop, which is a terminal-vs-
worksheet layout difference, not a theme one.) The dark prop and the
dark && "dark bg-dark-bg" class at ResultView.tsx:237 are removed; TerminalPanel's
hardcoded bg-dark-bg becomes the token-driven bg-background (the nested dark theme
sets --color-background to the dark value).
Monaco. In monaco/core.ts, register one Monaco theme per preset via
buildMonacoTheme(preset), which maps the preset's editor colors → Monaco colors{}
and its syntax palette → Monaco token rules[] (including SQL scopes). This replaces
the current callCssVariable()/:root reads — required because Monaco is
canvas-rendered and cannot see container-scoped CSS overrides, and because named themes
carry their own syntax colors rather than tinting vs/vs-dark. All six themes are
defined at init (monaco.editor.defineTheme(\bb-${id}`, …)`).
The Monaco theme is a single global value — it cannot be per-scope.
monaco.editor.setTheme applies to all standalone editors at once; Monaco has no
per-instance theme. So unlike the chrome (which is genuinely per-scope via CSS cascade),
every visible Monaco editor shares one theme. Concretely, more than one Monaco can be
on screen simultaneously: the access-request drawer hosts its own editor
(AccessGrantRequestDrawer.tsx:262) and can be open over an admin terminal — so a
"one code panel at a time" assumption does not hold.
The SQL Editor therefore maintains one active Monaco theme, derived from the
foreground code surface: worksheet → the selected theme; admin →
resolveAdminTheme(selected) (useActiveSQLEditorTheme()). It is applied two ways that
agree on the value:
- The SQL-Editor editors (
StandardPanel/SQLEditor,TerminalPanel/CompactSQLEditor, and the drawer's editor) pass an explicitthemeoption =monacoThemeName(active), so the sharedMonacoEditorsets the right theme on construction (nobb-lightflash).CompactSQLEditordrops its hardcodedtheme: "vs-dark"for this. - A single controller hook
useMonacoThemeController()(mounted once at the SQL-Editor root) re-applies the active theme onthemeId/modechange viamonaco.editor.setTheme(getResolvedTheme(monacoThemeName(active)))— covering live switches while editors stay mounted.
getResolvedTheme is mandatory here: in runtime modes where the vscode theme-service
override prevents a custom theme from registering (initializeTheme only adds a name to
registeredThemes after defineTheme succeeds), calling setTheme with an unregistered
name is a silent no-op; getResolvedTheme falls back to the always-available
bb-light/vs, so a named theme can never leave Monaco stuck on a stale theme.
Boundary & non-SQL Monaco (scope decision). setTheme is global, but the shared
MonacoEditor is left unchanged: editors that pass no explicit theme — every non-SQL
Monaco surface in the app — keep resetting to the default bb-light on construction. So
while the SQL Editor is mounted the controller owns the global Monaco theme; elsewhere
each editor resets itself. Containment guarantee: useMonacoThemeController also
resets the global Monaco theme back to bb-light on unmount (a separate []-effect
cleanup), so the SQL Editor's selected theme never lingers on app-scope Monaco after the
user leaves — covering even an already-mounted/kept-alive non-SQL editor that wouldn't
re-run its own construction reset. Because the SQL Editor is a full-page view, non-SQL
Monaco is never on screen alongside it, so this split is invisible in normal navigation —
no app-wide Monaco change is needed now. (Monaco's hard limit: two editors visible at the
same instant cannot have different themes — there is one global theme. This never occurs
here because the SQL Editor doesn't share the screen with another Monaco surface.) App-level Monaco (all editors follow the preference)
was considered and rejected for v1: it would require coupling the shared MonacoEditor
to the theme preference + an app-root controller + an app-level store — broad blast radius
for a benefit that is only theoretical today. See Extensibility to app scope (Future
work) for the small lift path.
When the access drawer is open, its Monaco adopts the active theme (passes the same active Monaco name), so it never competes with the terminal for the global theme. Consequence: opening the drawer over a light-selected admin tab shows a dark statement editor (matching the visible terminal) — acceptable, since per-editor Monaco themes are impossible.
5. Color migration (prerequisite)
Scoped overrides only reach components that use the tokens. The following bypass them and must be migrated. Two rules:
- Replace raw palette classes / inline colors with the semantic token equivalent.
- Delete
dark:-prefixed variants — dark theming now flows through token values supplied by the active (root or nested) theme scope, not a global.darkclass. Thedarkboolean prop threaded throughResultViewis removed; the rare consumer that needs the Monaco family readsuseSQLEditorTheme().monacoBase, but no component branches colors on a boolean. In admin mode the result grid renders dark because it sits inside the nested admin scope, not because ofdark:classes.
Result views (currently dark:-driven):
ResultView/VirtualDataTable.tsx— lines 271, 275, 311, 313, 397, 436, 496 (grid borders, header bg/text/hover, data cells, resize handle)ResultView/VirtualDataBlock.tsx— lines 147, 153, 166, 237 (block title/content/card bg, delete button)ResultView/SelectionCopyTooltips.tsx— lines 56, 62, 75, 153 (selection toolbar, info icon, copy button, menu item)ResultView/SingleResultView.tsx— lines 602, 617 (copy-cell buttons)ResultPanel/DatabaseQueryContext.tsx— lines 75, 93 (bg-white/80+dark:bg-black/80overlays → token-based overlay)
Standard-mode raw palette colors:
ConnectionPane/DatabaseHoverPanel/DatabaseHoverPanel.tsx— 97, 114, 124, 133, 142, 149ConnectionPane/ConnectionPane.tsx— 680 (bg-white/75loading overlay)SQLEditorHomePage.tsx— 164 (bg-whiteFAB), 194 (bg-black/40backdrop)SQLEditorLayout.tsx— 58 (debug panel; low priority, dev-only)SchemaPane/FlatTableList.tsx— 169, 174, 206, 209, 218, 221, 227, 228, 237, 240SchemaPane/TreeNode/icons.tsx— 43, 54, 59, 71, 87, 91, 126SchemaPane/HoverPanel/HoverPanel.tsx— 142;HoverPanel/InfoItem.tsx— 22SharePopoverBody.tsx— 182, 197, 198, 236, 247Panels/common/EllipsisCell.tsx— 70 (bg-gray-900 text-whitetooltip)
Inline rgb/hex — keep as-is (dynamic, not theme tokens):
ConnectionPane/TreeNode/Label.tsx90–91,TabItem/TabItem.tsx72/77/78,ResultPanel/BatchQuerySelect.tsx451–455 — these derive from per-environment colors and the indigo fallback; out of scope for theming.AccessGrantItem.tsx233–234 — animation keyframe; leave unless it clashes on dark.
Admin / terminal — now themed via the nested scope (not pinned):
TerminalPanel/TerminalPanel.tsx— outermostbg-dark-bg(206) and innerbg-dark-bg(208) becomebg-background; wrap the root div in the nestedSQLEditorThemeScope(resolved admin theme). Overlays at 246 (bg-black/20), 251 (text-gray-400) route through tokens.CompactSQLEditor.tsx:323— drop hardcodedtheme: "vs-dark"; let the global Monaco controller (§4 → Monaco) drive the theme.- The result-view
dark:variants listed above are removed here too — in admin mode they now get dark token values from the nested scope. The admin terminal is no longer a special-cased aesthetic; it is just the resolved admin theme applied to a nested scope.
6. Switcher UI
Add a preset selector using the shared React Select (a dropdown — preferred over a
radio group now that the catalog has six entries). It is its own small component
ThemeSelect placed in EditorAction.tsx's action-right group (next to
ChooserGroup / OpenAIButton).
Why not
QueryContextSettingPopover(the original draft target): that popover early-returnsnullin admin mode (currentTabMode !== "ADMIN"), so a switcher there would disappear in exactly the mode we are theming.EditorActionis rendered by bothStandardPanelandTerminalPanel, and itsaction-rightgroup is always visible — so the theme control is reachable in worksheet and admin alike.
Options are driven off the PRESETS array (so adding a theme needs no UI change). Each
label uses the preset's name i18n key; built-in palette names (Solarized, Monokai,
Nord) are proper nouns and stay untranslated as values. The current value and onChange
bind to useSQLEditorEditorState((s) => s.themeId) / setThemeId.
Data flow
CHROME (per-scope, CSS cascade):
localStorage ──load──▶ useSQLEditorEditorStore.themeId ──set by──▶ QueryContextSettingPopover (Select)
│
▼
Root SQLEditorThemeScope at SQLEditorLayout (selected preset)
· inline --color-* on the layout container → CSS cascade re-themes chrome
· provides theme via context (reaches RequestDrawerHost + portals)
│
┌──────────────────┬───────┴───────────────────┬───────────────────────────┐
▼ (worksheet tab) ▼ (admin tab) ▼ (overlay portals + request drawer)
root scope only Nested SQLEditorThemeScope Nested SQLEditorThemeScope per portal
(selected tokens) theme=resolveAdminTheme(sel) · context read via useSQLEditorTheme()
· --color-* on TerminalPanel (portals preserve context, not CSS)
root (overrides parent) · re-applies --color-* on portaled DOM
· ResultView is token-driven (drawer Sheet chrome, FAB, sidebar)
(compact prop = layout only)
MONACO (single global, driven by foreground panel — cannot be per-scope):
{ tab mode, selected themeId } ──▶ active = mode==="ADMIN" ? resolveAdminTheme(sel) : sel
│
▼
monaco.editor.setTheme(`bb-${active.id}`) // one global theme
│
┌─────────────────────────┼─────────────────────────┐
▼ ▼ ▼
worksheet/terminal editor drawer's Monaco (if open) any other Monaco
── all share the one active theme ──
Testing
- Unit:
validateTheme()passes for all six presets (every required chrome token, everyeditorkey, everysyntaxkey present — no holes);themeToCssVars(theme)(the helperSQLEditorThemeScopeuses) returns the correctCSSPropertiesfor a given theme;buildMonacoThememapseditor/syntaxonto Monacocolors/rulescorrectly; store persists/restoresthemeIdand falls back tolighton invalid input. - Component: rendering
sqleditor--wrapperwith each preset applies the expected CSS vars; switchingthemeIdupdates them.resolveAdminThemereturns the selected theme when dark anddarkwhen light. A nestedSQLEditorThemeScopeoverrides the parent's CSS vars for its subtree. - Manual/visual: Light preset is visually identical to current
main; each of the other five renders chrome + result grid + Monaco coherently (no un-themed islands, syntax colors match the named theme's identity). Admin mode: with a light theme selected, the terminal subtree is dark while chrome stays light; with a dark theme selected, the terminal matches it. With a non-light theme selected, also confirm the portaled surfaces theme correctly: the mobile FAB + sidebar overlay, and the access-request drawer (AccessGrantRequestDrawer) chrome — none should fall back to light. Drawer-Monaco conflict: open the drawer over an admin terminal and confirm neither editor flickers/ends on the wrong theme — both share the one active global Monaco theme (the documented trade-off), not a fight that leaves one wrong. Checked throughpnpm --dir frontend dev. - Gates:
pnpm --dir frontend fix,check,type-check,test.
Risks
- Migration breadth (Section 5) is the bulk of the work and the main risk. Missing
an offender shows up as an un-themed element on dark. Mitigate by grepping for
dark:,-gray-,-zinc-,-slate-,bg-white,bg-blackunder the SQL Editor tree after migration and confirming zero remain (excluding the admin terminal and the documented dynamic/animation cases). - Portals break CSS-variable cascade. Surfaces portaled to the app-global layer
roots (mobile FAB / sidebar overlay) and the
RequestDrawerHostsibling (incl. its Monaco) do not inherit the chrome scope's--color-*by DOM cascade. Mitigate by raising the root scope toSQLEditorLayout(context reaches the drawer) and wrapping each portal's children in a nestedSQLEditorThemeScopethat re-applies the vars (it reads the theme via the context the portal preserves). Verify each portaled surface under a dark/named theme; a missed portal renders light-on-dark. - Removing the
darkprop / nested admin scope.ResultViewis shared between worksheet and terminal; after dropping the prop it must read the theme from context. Verify: (a) worksheet result grid follows the selected theme, (b) terminal result grid is dark via the nested scope, (c) entering/leaving admin mid-session re-themes both the chrome boundary and Monaco, (d) the nested scope's CSS-var override actually wins over the root scope for the whole terminal subtree (no leaked light tokens). - Monaco theme generation replaces
callCssVariablereads; confirm the generatedbb-equivalent matches the current editor look pixel-for-pixel on light. - Monaco's theme is global, not per-instance. Multiple editors can be visible at once
(terminal + access-drawer Monaco), but
setThemerepaints all of them. The design resolves this by driving one global theme from the foreground panel and having the drawer adopt it (§4 → Monaco), rather than per-editor themes (impossible in Monaco). Risk if implemented naively as "each editor sets its own theme": last-writer-wins flicker / wrong theme. The single-controller approach must own everysetThemecall; no component should callsetThemeindependently. - Named-theme authoring fidelity. Six palettes (incl. four named themes with full
syntax sets) must be derived from published references and checked against contrast
needs for both chrome text and result-grid readability. This is real per-theme design
effort and the second-largest cost after the migration. Author each as its own file
so they can be reviewed/tuned independently; the
validateTheme()test guards structural completeness but not aesthetic quality — that needs a visual pass.
Future work (out of scope)
Custom theme editor — planned next. A user-defined theme is just another
SQLEditorThemeobject, so the application/override path (scope cascade + Monaco) needs no change; the editor UI's only job is to produce a valid object (color pickers / JSON), guarded by the existingvalidateTheme. Confirmed direction (2026-06-15) — not built in v1. Landing it cleanly relies on three seams this design already establishes; keep them intact:- Single resolution point —
resolveThemeId(id)is the only place that turns an id into a theme. Grow its source fromPRESET_BY_ID→{ …presets, …custom }in that one spot; everything downstream takes the resolved object. SQLEditorThemestays plain serializable data (token map of"r g b"strings- hex strings — no functions/refs), so it persists to localStorage now and maps
cleanly to a proto/
Settinglater.
- hex strings — no functions/refs), so it persists to localStorage now and maps
cleanly to a proto/
- Runtime Monaco registration — presets are
defineTheme'd once at init (monaco/core.ts); custom themes need the samedefineTheme("bb-<id>", …)on create/edit (elsegetResolvedThemefalls back tobb-light).
The
namefield is already a plain literal label (no i18n — the switcher is dev-only, so theme names aren't translated), so a custom theme just setsnameto the user's string; nothing special is needed there.- Single resolution point —
Backend / cross-device persistence — later (not now). Confirmed direction (2026-06-15): the selected id + any custom theme objects move from localStorage to a user/workspace
Setting, with localStorage as the offline/default fallback. No proto or store-shape change in v1; the serializable model (seam #2 above) makes this additive."System" preset following
prefers-color-scheme.
Extensibility to app scope
The architecture is deliberately liftable to app-wide with a small, well-understood change — not a rewrite — should that ever be wanted (a maintainer raised it; deferred as out of scope for v1 to keep complexity/time down):
- Chrome.
SQLEditorThemeScopeand the token model already override the global--color-*names. Lifting = mount the scope at the app root instead of the SQL-Editor container. As a bonus, the portal problem vanishes (tokens at app root cascade into the shared overlay root). - Monaco. Move
useMonacoThemeController()from the SQL-Editor root to the app root, and change the sharedMonacoEditor's construction-time reset to use the active preference instead of the hardcodedbb-lightdefault — then every Monaco surface follows the preference. - Preference. Move
themeIdfrom the SQL-Editor store to an app-level (workspace/ user-scoped) store, and relocate the switcher from the editor toolbar to a global appearance/settings surface.
Each step is independent and the token/preset/scope code is unchanged.
Open questions
- Exact palette values for
darkand the four named themes — the tables/references above are starting points; confirm chrome + syntax values visually during implementation. - Ordering of presets in the switcher dropdown (proposed: Default Light, Default Dark, Solarized Light, Solarized Dark, Monokai, Nord).
- Admin scope when the selected theme is light: falls back to
dark(decided). Confirm that picking a dark theme and entering admin simply keeps that theme (no separate "terminal" identity / matrix-green) — assumed yes.