Skip to content

Self-improving AI Employees for everyone

feat(theme): 4-way theme system + design-handoff token contract

trohitg52c52293bc20
diff --git a/CLAUDE.md b/CLAUDE.md
index 31fb63fe..e19e79fe 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -11,6 +11,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
|----------|-------------|
| **[Frontend Architecture](./docs-internal/frontend_architecture.md)** | Current frontend stack (React 19 + Vite + Tailwind v4 + shadcn/ui + Radix + RHF/zod + TanStack Query + Zustand). Tokens, primitives, forms, credentials exemplar, ownership boundary, `uiHints` catalogue. |
| **[UI Migration Plan](./docs-internal/ui_migration_plan.md)** | antd → shadcn/ui migration plan + completion log. Waves 1–10 done. Full frontend is schema-driven (backend SSOT); remaining DIY widget registry (ex-Phase 6) is the one deferred item. |
+| **[Theme System](./docs-internal/theme_system.md)** | 4-way visual theme system (light / dark / renaissance / cyber) driven by `<html data-theme>` + per-theme CSS files in `client/src/themes/`. Token taxonomy (surface / fg / border / accent / typography / motion), migration recipe, anti-patterns, file index. Read this before adding a new theme or migrating a component to the new contract. |
| **[Schema Source of Truth RFC](./docs-internal/schema_source_of_truth_rfc.md)** | Backend is SSOT for node schemas, visual metadata, handlers, palette metadata, icons. Plugin pattern: one `BaseNode` subclass in `server/nodes/<group>/<name>.py`. Wire format: `asset:<key>` / `<lib>:<brand>` / URL / emoji. Endpoint: `/api/schemas/nodes/{type}/spec.json`. 124 pytest invariants lock the contract. |
| **[Plugin System (Wave 11)](./docs-internal/plugin_system.md)** | Class-based plugin-first architecture. `BaseNode` / `ActionNode` / `TriggerNode` / `ToolNode` + `@Operation` decorator. Pydantic `Params`/`Output`. Declarative `Routing` DSL + `Connection` facade (Nango pattern). 18 `Credential` subclasses live in each node folder's `_credentials.py` (or inline for single-use). `TaskQueue` constants route to Temporal worker pools. 111 plugins live across 9 queues; handler bodies fully inlined (`services/handlers/` shrank 12.8K → 1.1K LOC across 16 → 4 files; only cross-cutting orchestration remains: `tools.py` AI-tool dispatch + agent delegation, `google_auth.py`, `triggers.py`). **Wave 11.H added "self-contained plugin folders"** — five generic registries (`ws_handler_registry`, `event_waiter.{register_filter_builder,register_trigger_precheck}`, `status_broadcaster.register_service_refresh`, `node_output_schemas.register_output_schema`) so rich plugins like telegram own their entire surface area without core-services edits. |
| **[Nodes Cookbook](./server/nodes/README.md)** | 5-minute recipe + folder map + shared helpers (`_base.py` / `_inline.py` per domain) + shared credentials + **self-contained plugin folder pattern (telegram reference)** + contract invariants + common pitfalls. Lives next to the plugin files. |
diff --git a/client/index.html b/client/index.html
index e55c9690..f9752ebe 100644
--- a/client/index.html
+++ b/client/index.html
@@ -4,7 +4,34 @@
<meta charset="UTF-8" />
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <title>React Flow Project</title>
+ <!--
+ Theme typography. Each theme picks its display + body + mono via
+ the --font-display / --font-body / --font-mono tokens. Loading
+ these as `media="print" onload=...` defers the network cost so
+ the default light/dark theme (system fonts via @fontsource-
+ variable/geist bundled at build time) renders without blocking,
+ and Renaissance + Cyber fonts swap in once their stylesheets land.
+
+ Renaissance: Cinzel (display), Cormorant Garamond (body),
+ IM Fell English (mono / italic accents).
+ Cyber: Major Mono Display (display), VT323 (body fallback),
+ JetBrains Mono (body + mono).
+ -->
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+ <link
+ rel="stylesheet"
+ href="https://fonts.googleapis.com/css2?family=Cinzel:wght@400;600;700&family=Cormorant+Garamond:ital,wght@0,400;0,500;0,600;1,400&family=IM+Fell+English:ital@0;1&family=JetBrains+Mono:wght@400;500;600;700&family=Major+Mono+Display&family=VT323&display=swap"
+ media="print"
+ onload="this.media='all'"
+ />
+ <noscript>
+ <link
+ rel="stylesheet"
+ href="https://fonts.googleapis.com/css2?family=Cinzel:wght@400;600;700&family=Cormorant+Garamond:ital,wght@0,400;0,500;0,600;1,400&family=IM+Fell+English:ital@0;1&family=JetBrains+Mono:wght@400;500;600;700&family=Major+Mono+Display&family=VT323&display=swap"
+ />
+ </noscript>
+ <title>MachinaOS</title>
</head>
<body>
<div id="root"></div>
diff --git a/client/src/Dashboard.tsx b/client/src/Dashboard.tsx
index 53a93f57..e1186138 100644
--- a/client/src/Dashboard.tsx
+++ b/client/src/Dashboard.tsx
@@ -35,6 +35,8 @@ import CredentialsModal from './components/CredentialsModal';
import OnboardingWizard from './components/onboarding/OnboardingWizard';
import ErrorBoundary from './components/ui/ErrorBoundary';
import ConsolePanel from './components/ui/ConsolePanel';
+import StatusBar from './components/ui/StatusBar';
+import CommandPaletteHost from './components/ui/CommandPaletteHost';
import { useAppTheme } from './hooks/useAppTheme';
import { useWorkflowManagement } from './hooks/useWorkflowManagement';
import { useWorkflowsQuery, WORKFLOWS_QUERY_KEY } from './hooks/useWorkflowsQuery';
@@ -277,6 +279,7 @@ const DashboardContent: React.FC = () => {
const [settingsOpen, setSettingsOpen] = React.useState(false);
const [credentialsOpen, setCredentialsOpen] = React.useState(false);
const [onboardingReopenTrigger, setOnboardingReopenTrigger] = React.useState(0);
+ const [commandPaletteOpen, setCommandPaletteOpen] = React.useState(false);
// Console panel visibility from store (database-backed)
const consolePanelVisible = useAppStore((state) => state.consolePanelVisible);
@@ -1240,6 +1243,35 @@ const DashboardContent: React.FC = () => {
nodes={nodes}
/>
+ {/* Status bar — fixed-bottom system console line; surfaces
+ connection state, workflow context, theme, clock. Always
+ present below ConsolePanel. */}
+ <StatusBar workflowName={currentWorkflow?.name} nodeCount={nodes.length} />
+
+ {/* Global command palette — ⌘K (Ctrl+K). Surface common shell
+ actions; the registered list is local to this component
+ because every handler is already in scope here. */}
+ <CommandPaletteHost
+ open={commandPaletteOpen}
+ onOpenChange={setCommandPaletteOpen}
+ handlers={{
+ save: handleSave,
+ newWorkflow: handleNew,
+ open: handleOpen,
+ run: handleDeploy,
+ stop: handleCancelDeployment,
+ isDeploying: isCurrentWorkflowActive,
+ exportFile: handleExportFile,
+ importJSON: handleImportJSON,
+ openSettings: () => setSettingsOpen(true),
+ openCredentials: () => setCredentialsOpen(true),
+ toggleSidebar,
+ toggleComponentPalette,
+ toggleConsolePanel: toggleConsolePanelVisible,
+ }}
+ />
+
+
{/* Parameter Panels */}
<ErrorBoundary>
<ParameterPanel />
diff --git a/client/src/components/ui/CollapsibleSection.tsx b/client/src/components/ui/CollapsibleSection.tsx
index 27fef738..283d08fe 100644
--- a/client/src/components/ui/CollapsibleSection.tsx
+++ b/client/src/components/ui/CollapsibleSection.tsx
@@ -23,16 +23,19 @@ const CollapsibleSection: React.FC<CollapsibleSectionProps> = ({
const open = !isCollapsed;
return (
<Collapsible open={open} onOpenChange={() => onToggle()}>
- <div className="overflow-hidden rounded-lg border border-border bg-background">
- <CollapsibleTrigger className="flex w-full cursor-pointer items-center justify-between gap-2 border-none bg-muted px-4 py-3 text-base text-foreground transition-colors hover:bg-card">
+ {/* bg-bg-app + border-default for the outer card; bg-bg-elevated
+ on the trigger so the head sits above the body — matches the
+ handoff `.cat` / `.cat-head` two-tier surface. */}
+ <div className="overflow-hidden rounded-lg border border-border-default bg-bg-app">
+ <CollapsibleTrigger className="flex w-full cursor-pointer items-center justify-between gap-2 border-none bg-bg-elevated px-4 py-3 text-base text-fg-default transition-colors hover:bg-bg-hover">
{typeof title === 'string' ? (
- <span className="font-medium">{title}</span>
+ <span className="font-display font-medium">{title}</span>
) : (
<div className="flex flex-1 items-center">{title}</div>
)}
<ChevronDown
className={cn(
- 'h-3 w-3 shrink-0 text-muted-foreground transition-transform',
+ 'h-3 w-3 shrink-0 text-fg-muted transition-transform',
isCollapsed && '-rotate-90'
)}
/>
diff --git a/client/src/components/ui/CommandPalette.tsx b/client/src/components/ui/CommandPalette.tsx
new file mode 100644
index 00000000..cdeb8fec
--- /dev/null
+++ b/client/src/components/ui/CommandPalette.tsx
@@ -0,0 +1,147 @@
+/**
+ * CommandPalette — global ⌘K (Ctrl+K) command launcher.
+ *
+ * Lightweight shell action surface inspired by the design handoff's
+ * `.cmdk` panel. Keeps a small registered command set in state; the
+ * Dashboard wires the actual handlers (`onOpenSettings`, etc.) via the
+ * `commands` prop. Composes on top of the cmdk library that ships with
+ * the codebase (CredentialsPalette uses the same dependency).
+ *
+ * Token-driven: chrome reads bg-bg-elevated + border-border-strong;
+ * active row reads bg-bg-active + text-accent. Under Renaissance the
+ * panel becomes an "open scroll" via the per-theme background image
+ * (declared in renaissance.css `.cmdk` block — wired through here by
+ * applying the `cmdk` class on the outer wrapper). Under Cyber it
+ * becomes a "root terminal" with neon-cyan border + scanlines.
+ */
+
+import * as React from 'react';
+import { useEffect } from 'react';
+import { Command } from 'cmdk';
+import { Search } from 'lucide-react';
+import { Dialog, DialogPortal, DialogOverlay, DialogTitle, DialogDescription } from '@/components/ui/dialog';
+import { Dialog as DialogPrimitive } from 'radix-ui';
+import { cn } from '@/lib/utils';
+
+export interface CommandItem {
+ id: string;
+ label: string;
+ hint?: string;
+ shortcut?: string;
+ /** lucide-react icon component */
+ icon?: React.ComponentType<{ className?: string }>;
+ /** Group label used to bucket items in the list. */
+ group?: string;
+ /** Invoked when the user presses Enter / clicks the row. */
+ onRun: () => void;
+}
+
+interface CommandPaletteProps {
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+ commands: CommandItem[];
+}
+
+export const CommandPalette: React.FC<CommandPaletteProps> = ({ open, onOpenChange, commands }) => {
+ // ⌘K / Ctrl+K toggles the palette globally.
+ useEffect(() => {
+ const handler = (e: KeyboardEvent) => {
+ if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
+ e.preventDefault();
+ onOpenChange(!open);
+ } else if (e.key === 'Escape' && open) {
+ onOpenChange(false);
+ }
+ };
+ window.addEventListener('keydown', handler);
+ return () => window.removeEventListener('keydown', handler);
+ }, [open, onOpenChange]);
+
+ // Bucket commands by group so the list renders Command.Group sections.
+ const groups = React.useMemo(() => {
+ const buckets: Record<string, CommandItem[]> = {};
+ for (const cmd of commands) {
+ const key = cmd.group ?? 'Actions';
+ (buckets[key] ??= []).push(cmd);
+ }
+ return buckets;
+ }, [commands]);
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogPortal>
+ <DialogOverlay className="bg-bg-overlay" />
+ <DialogPrimitive.Content
+ data-slot="command-palette"
+ className={cn(
+ // `cmdk` class is the per-theme decorative hook (renaissance
+ // and cyber CSS apply backgrounds + borders + scanlines via
+ // `:root[data-theme="..."] .cmdk`).
+ 'cmdk fixed left-1/2 top-[14%] z-50 w-[min(560px,92vw)] -translate-x-1/2 overflow-hidden rounded-md border border-border-strong bg-bg-elevated shadow-2xl outline-none',
+ 'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 duration-100',
+ )}
+ >
+ <DialogTitle className="sr-only">Command palette</DialogTitle>
+ <DialogDescription className="sr-only">Run a command from the keyboard</DialogDescription>
+
+ <Command label="Command palette" className="flex flex-col" shouldFilter>
+ <div className="relative border-b border-border-default px-4">
+ <Search className="pointer-events-none absolute left-4 top-1/2 h-4 w-4 -translate-y-1/2 text-fg-muted" />
+ <Command.Input
+ placeholder="Type a command or search..."
+ autoFocus
+ className="h-12 w-full bg-transparent pl-7 font-display text-[15px] tracking-[var(--type-tracking-display)] text-fg-default placeholder:text-fg-faint focus:outline-none [text-transform:var(--type-uppercase)]"
+ />
+ </div>
+
+ <Command.List className="max-h-[360px] overflow-y-auto p-1.5">
+ <Command.Empty className="px-3 py-6 text-center text-sm text-fg-muted">
+ No matching commands
+ </Command.Empty>
+
+ {Object.entries(groups).map(([groupName, items]) => (
+ <Command.Group
+ key={groupName}
+ heading={groupName}
+ className="px-1 py-1 text-[10px] font-semibold uppercase tracking-wider text-fg-faint"
+ >
+ {items.map((cmd) => {
+ const Icon = cmd.icon;
+ return (
+ <Command.Item
+ key={cmd.id}
+ value={`${cmd.label} ${cmd.hint ?? ''}`}
+ onSelect={() => {
+ onOpenChange(false);
+ // Defer the action one frame so the dialog
+ // closes cleanly before the handler fires
+ // (avoids focus-trap clashes when the action
+ // opens another modal).
+ requestAnimationFrame(() => cmd.onRun());
+ }}
+ className="flex cursor-pointer items-center gap-3 rounded-sm px-3 py-2 text-sm text-fg-default data-[selected=true]:bg-bg-active data-[selected=true]:text-accent"
+ >
+ {Icon && <Icon className="h-4 w-4 shrink-0" />}
+ <span className="flex-1 truncate font-display">{cmd.label}</span>
+ {cmd.hint && (
+ <span className="font-mono text-[11px] text-fg-faint">{cmd.hint}</span>
+ )}
+ {cmd.shortcut && (
+ <kbd className="ml-auto rounded-sm border border-border-default bg-bg-app px-1.5 py-0.5 font-mono text-[10px] text-fg-muted">
+ {cmd.shortcut}
+ </kbd>
+ )}
+ </Command.Item>
+ );
+ })}
+ </Command.Group>
+ ))}
+ </Command.List>
+ </Command>
+ </DialogPrimitive.Content>
+ </DialogPortal>
+ </Dialog>
+ );
+};
+
+export default CommandPalette;
diff --git a/client/src/components/ui/CommandPaletteHost.tsx b/client/src/components/ui/CommandPaletteHost.tsx
new file mode 100644
index 00000000..d6505b53
--- /dev/null
+++ b/client/src/components/ui/CommandPaletteHost.tsx
@@ -0,0 +1,181 @@
+/**
+ * CommandPaletteHost — Dashboard-level command list registration.
+ *
+ * Owns the canonical command set that the global ⌘K palette surfaces.
+ * Receives every action as a handler prop (Dashboard already has them
+ * in scope) plus the active theme controls; assembles a `CommandItem[]`
+ * with stable IDs, hints, and keyboard shortcuts and renders the
+ * underlying CommandPalette.
+ *
+ * New shell action: add a handler to `Handlers`, wire it through from
+ * Dashboard, append a `CommandItem` to `commands` below. No edits to
+ * the CommandPalette primitive itself.
+ */
+
+import * as React from 'react';
+import {
+ Settings as SettingsIcon,
+ KeyRound,
+ Save,
+ Play,
+ Square,
+ FilePlus,
+ FolderOpen,
+ PanelLeftClose,
+ PanelRightClose,
+ Terminal,
+ Palette as PaletteIcon,
+ Download,
+ Upload,
+} from 'lucide-react';
+import { CommandPalette, type CommandItem } from './CommandPalette';
+import { AVAILABLE_THEMES, useTheme, type ThemeName } from '../../contexts/ThemeContext';
+
+interface Handlers {
+ save: () => void;
+ newWorkflow: () => void;
+ open: () => void;
+ run: () => void;
+ stop: () => void;
+ isDeploying: boolean;
+ exportFile: () => void;
+ importJSON: () => void;
+ openSettings: () => void;
+ openCredentials: () => void;
+ toggleSidebar: () => void;
+ toggleComponentPalette: () => void;
+ toggleConsolePanel: () => void;
+}
+
+const THEME_LABEL: Record<ThemeName, string> = {
+ light: 'Light',
+ dark: 'Dark',
+ renaissance: 'Renaissance',
+ cyber: 'Cyber-Tyranny',
+};
+
+interface Props {
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+ handlers: Handlers;
+}
+
+export const CommandPaletteHost: React.FC<Props> = ({ open, onOpenChange, handlers }) => {
+ const { theme, setTheme } = useTheme();
+
+ const commands: CommandItem[] = React.useMemo(() => {
+ const list: CommandItem[] = [
+ // ── Workflow ───────────────────────────────────────────────────
+ {
+ id: 'workflow.new',
+ label: 'New Workflow',
+ group: 'Workflow',
+ icon: FilePlus,
+ onRun: handlers.newWorkflow,
+ },
+ {
+ id: 'workflow.open',
+ label: 'Open Workflow',
+ group: 'Workflow',
+ icon: FolderOpen,
+ onRun: handlers.open,
+ },
+ {
+ id: 'workflow.save',
+ label: 'Save Workflow',
+ group: 'Workflow',
+ icon: Save,
+ shortcut: '⌘S',
+ onRun: handlers.save,
+ },
+ {
+ id: 'workflow.export',
+ label: 'Export Workflow',
+ group: 'Workflow',
+ icon: Download,
+ onRun: handlers.exportFile,
+ },
+ {
+ id: 'workflow.import',
+ label: 'Import Workflow',
+ group: 'Workflow',
+ icon: Upload,
+ onRun: handlers.importJSON,
+ },
+
+ // ── Run ────────────────────────────────────────────────────────
+ handlers.isDeploying
+ ? {
+ id: 'run.stop',
+ label: 'Stop Workflow',
+ group: 'Run',
+ icon: Square,
+ onRun: handlers.stop,
+ }
+ : {
+ id: 'run.start',
+ label: 'Start Workflow',
+ group: 'Run',
+ icon: Play,
+ onRun: handlers.run,
+ },
+
+ // ── Open panels ────────────────────────────────────────────────
+ {
+ id: 'open.settings',
+ label: 'Open Settings',
+ group: 'Open',
+ icon: SettingsIcon,
+ onRun: handlers.openSettings,
+ },
+ {
+ id: 'open.credentials',
+ label: 'Open Credentials',
+ group: 'Open',
+ icon: KeyRound,
+ onRun: handlers.openCredentials,
+ },
+
+ // ── View toggles ───────────────────────────────────────────────
+ {
+ id: 'view.sidebar',
+ label: 'Toggle Sidebar',
+ group: 'View',
+ icon: PanelLeftClose,
+ onRun: handlers.toggleSidebar,
+ },
+ {
+ id: 'view.palette',
+ label: 'Toggle Component Palette',
+ group: 'View',
+ icon: PanelRightClose,
+ onRun: handlers.toggleComponentPalette,
+ },
+ {
+ id: 'view.console',
+ label: 'Toggle Console / Chat Panel',
+ group: 'View',
+ icon: Terminal,
+ onRun: handlers.toggleConsolePanel,
+ },
+ ];
+
+ // ── Theme switch ─────────────────────────────────────────────────
+ for (const name of AVAILABLE_THEMES) {
+ list.push({
+ id: `theme.${name}`,
+ label: `Switch theme: ${THEME_LABEL[name]}`,
+ group: 'Theme',
+ icon: PaletteIcon,
+ hint: name === theme ? 'active' : undefined,
+ onRun: () => setTheme(name),
+ });
+ }
+
+ return list;
+ }, [handlers, theme, setTheme]);
+
+ return <CommandPalette open={open} onOpenChange={onOpenChange} commands={commands} />;
+};
+
+export default CommandPaletteHost;
diff --git a/client/src/components/ui/ComponentItem.tsx b/client/src/components/ui/ComponentItem.tsx
index 7eda8279..ea36eb26 100644
--- a/client/src/components/ui/ComponentItem.tsx
+++ b/client/src/components/ui/ComponentItem.tsx
@@ -22,6 +22,8 @@ const ComponentItem: React.FC<ComponentItemProps> = ({ definition: localDefiniti
const iconRaw = spec?.icon ?? definition.icon;
return (
+ // bg-bg-app + border-default match the handoff `.comp` card.
+ // Hover lifts via translate + outline + soft tint backdrop.
<Card
size="sm"
draggable
@@ -32,12 +34,12 @@ const ComponentItem: React.FC<ComponentItemProps> = ({ definition: localDefiniti
onDragEnd={() => setIsDragging(false)}
className={cn(
'group relative flex-row items-center gap-3 px-3 py-2 cursor-grab select-none',
- 'transition-all duration-150 ease-out',
- 'hover:-translate-y-0.5 hover:ring-2 hover:ring-foreground/15 hover:shadow-md',
+ 'border-border-default bg-bg-app transition-all duration-150 ease-out',
+ 'hover:-translate-y-0.5 hover:bg-bg-hover hover:ring-2 hover:ring-foreground/15 hover:shadow-md',
isDragging && 'opacity-50',
)}
>
- <div className="flex h-9 w-9 shrink-0 items-center justify-center rounded-md bg-muted ring-1 ring-foreground/10">
+ <div className="flex h-9 w-9 shrink-0 items-center justify-center rounded-md bg-bg-elevated ring-1 ring-border-default/40">
<NodeIcon
icon={iconRaw}
className="h-5 w-5 text-lg"
@@ -46,16 +48,16 @@ const ComponentItem: React.FC<ComponentItemProps> = ({ definition: localDefiniti
</div>
<div className="min-w-0 flex-1">
- <div className="truncate text-sm font-medium text-foreground">
+ <div className="truncate font-display text-sm font-medium text-fg-default">
{definition.displayName}
</div>
- <div className="truncate text-xs leading-tight text-muted-foreground">
+ <div className="truncate text-xs leading-tight text-fg-muted">
{definition.description}
</div>
</div>
<GripVertical
- className="h-4 w-4 shrink-0 text-muted-foreground opacity-30 transition-opacity group-hover:opacity-60"
+ className="h-4 w-4 shrink-0 text-fg-faint opacity-50 transition-opacity group-hover:opacity-80"
aria-hidden
/>
</Card>
diff --git a/client/src/components/ui/ComponentPalette.tsx b/client/src/components/ui/ComponentPalette.tsx
index fb747260..1b12e1ea 100644
--- a/client/src/components/ui/ComponentPalette.tsx
+++ b/client/src/components/ui/ComponentPalette.tsx
@@ -107,19 +107,22 @@ const ComponentPalette: React.FC<ComponentPaletteProps> = ({
);
return (
- <div className="flex h-full w-full flex-col overflow-hidden bg-muted/30">
- {/* Header Section */}
- <div className="border-b border-border bg-card p-4">
+ // Palette shell: bg-bg-panel mirrors the sidebar (`.palette` token).
+ <div className="flex h-full w-full flex-col overflow-hidden border-l border-border-default bg-bg-panel">
+ {/* Header Section — bg-bg-app drops one elevation step. */}
+ <div className="border-b border-border-default bg-bg-app p-4">
<div className="mb-3 flex items-center justify-between">
- <h2 className="text-base font-semibold text-foreground">Components</h2>
- <Badge variant="secondary" className="text-xs font-medium">
+ <h2 className="font-display text-base font-semibold tracking-[var(--type-tracking-display)] text-fg-default [text-transform:var(--type-uppercase)]">
+ Components
+ </h2>
+ <Badge variant="secondary" className="font-mono text-xs font-medium">
{totalComponents}
</Badge>
</div>
{/* Search Input */}
<div className="relative">
- <Search className="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
+ <Search className="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-fg-faint" />
<Input
type="text"
placeholder="Search..."
@@ -135,7 +138,7 @@ const ComponentPalette: React.FC<ComponentPaletteProps> = ({
{groupsLoading ? (
<PaletteSkeleton />
) : Object.keys(categorizedComponents).length === 0 ? (
- <div className="flex flex-col items-center px-6 py-12 text-center text-muted-foreground">
+ <div className="flex flex-col items-center px-6 py-12 text-center text-fg-muted">
<Search className="mb-3 h-12 w-12 opacity-50" />
<p className="text-sm">
No components found matching "{searchQuery}"
@@ -167,7 +170,7 @@ const ComponentPalette: React.FC<ComponentPaletteProps> = ({
fallback={<span>📦</span>}
/>
</span>
- <span className="text-sm font-semibold text-foreground">
+ <span className="font-display text-sm font-semibold tracking-[var(--type-tracking-display)] text-fg-default [text-transform:var(--type-uppercase)]">
{config.label}
</span>
</div>
diff --git a/client/src/components/ui/ConsolePanel.tsx b/client/src/components/ui/ConsolePanel.tsx
index 40453cc4..db1a4350 100644
--- a/client/src/components/ui/ConsolePanel.tsx
+++ b/client/src/components/ui/ConsolePanel.tsx
@@ -386,7 +386,7 @@ const ConsolePanel: React.FC<ConsolePanelProps> = ({
{/* Panel Header */}
<div
onClick={onToggle}
- className="flex cursor-pointer items-center justify-between border-t border-border bg-card px-3 py-1.5 select-none"
+ className="flex cursor-pointer items-center justify-between border-t border-border-default bg-bg-elevated px-3 py-1.5 select-none"
>
<div className="flex items-center gap-2">
<ChevronDown
@@ -395,7 +395,7 @@ const ConsolePanel: React.FC<ConsolePanelProps> = ({
!isOpen && 'rotate-180'
)}
/>
- <span className="flex items-center gap-1.5 text-sm font-semibold text-foreground">
+ <span className="flex items-center gap-1.5 font-display text-sm font-semibold tracking-[var(--type-tracking-display)] text-fg-default [text-transform:var(--type-uppercase)]">
Chat / Console
{(consoleLogs.length > 0 || (chatMessages && chatMessages.length > 0)) && (
<Badge variant="secondary" className="text-xs">
@@ -411,7 +411,7 @@ const ConsolePanel: React.FC<ConsolePanelProps> = ({
ref={containerRef}
style={{ height: isOpen ? `${panelHeight}px` : '0px' }}
className={cn(
- 'flex flex-row overflow-hidden bg-background',
+ 'flex flex-row overflow-hidden bg-bg-app',
'max-h-[calc(100vh-90px)]',
(isResizing || isHorizontalResizing) ? '[transition:none]' : 'transition-[height] duration-200 ease-in-out'
)}
@@ -422,9 +422,9 @@ const ConsolePanel: React.FC<ConsolePanelProps> = ({
className="relative flex flex-col overflow-hidden"
>
{/* Header */}
- <div className="flex min-h-[32px] items-center justify-between border-b border-border bg-card px-3 py-1.5">
+ <div className="flex min-h-[32px] items-center justify-between border-b border-border-default bg-bg-elevated px-3 py-1.5">
<div className="flex items-center gap-2">
- <span className="flex items-center gap-1.5 text-sm font-semibold text-foreground">
+ <span className="flex items-center gap-1.5 font-display text-sm font-semibold tracking-[var(--type-tracking-display)] text-fg-default [text-transform:var(--type-uppercase)]">
Chat
{chatMessages && chatMessages.length > 0 && (
<Badge variant="success" className="text-xs">{chatMessages.length}</Badge>
@@ -486,7 +486,7 @@ const ConsolePanel: React.FC<ConsolePanelProps> = ({
'max-w-[80%] px-3 py-2 break-words',
isUser
? 'mr-0 ml-auto rounded-l-xl rounded-tr-xl rounded-br-sm bg-node-agent-soft'
- : 'mr-auto ml-0 rounded-r-xl rounded-tl-xl rounded-bl-sm bg-card'
+ : 'mr-auto ml-0 rounded-r-xl rounded-tl-xl rounded-bl-sm border border-border-default bg-bg-elevated'
)}
>
{isUser ? (
@@ -512,7 +512,7 @@ const ConsolePanel: React.FC<ConsolePanelProps> = ({
</div>
{/* Input */}
- <div className="flex items-center gap-2 border-t border-border bg-card px-4 py-2.5">
+ <div className="flex items-center gap-2 border-t border-border-default bg-bg-elevated px-4 py-2.5">
<Input
ref={chatInputRef}
type="text"
@@ -549,7 +549,7 @@ const ConsolePanel: React.FC<ConsolePanelProps> = ({
{/* ===================== Console / Terminal Section (right) ===================== */}
<div className="flex flex-1 flex-col overflow-hidden">
{/* Header with tabs + filters */}
- <div className="flex min-h-[32px] items-center justify-between border-b border-border bg-card px-3 py-1.5">
+ <div className="flex min-h-[32px] items-center justify-between border-b border-border-default bg-bg-elevated px-3 py-1.5">
{/* Tab buttons */}
<div className="flex items-center gap-1">
<button
diff --git a/client/src/components/ui/Modal.tsx b/client/src/components/ui/Modal.tsx
index e68cb3d4..e188bbcf 100644
--- a/client/src/components/ui/Modal.tsx
+++ b/client/src/components/ui/Modal.tsx
@@ -65,11 +65,18 @@ const Modal: React.FC<ModalProps> = ({
return (
<Dialog open={isOpen} onOpenChange={(next) => { if (!next) onClose(); }}>
<DialogPortal>
- <DialogOverlay className="bg-black/50 supports-backdrop-filter:backdrop-blur-xs" />
+ {/* bg-bg-overlay reads --bg-overlay (each theme owns its own
+ scrim alpha + tone — Renaissance uses ink-brown, Cyber uses
+ void-near-black, light/dark use plain blacks). */}
+ <DialogOverlay className="bg-bg-overlay supports-backdrop-filter:backdrop-blur-xs" />
<DialogPrimitive.Content
data-slot="dialog-content"
className={cn(
- 'fixed top-1/2 left-1/2 z-50 flex -translate-x-1/2 -translate-y-1/2 flex-col overflow-hidden rounded-lg border border-border bg-background shadow-2xl outline-none',
+ // bg-bg-app + border-border-default consume the new-contract
+ // tokens directly so modals inherit the surface hierarchy
+ // defined by the active theme (parchment under Renaissance,
+ // void under Cyber).
+ 'fixed top-1/2 left-1/2 z-50 flex -translate-x-1/2 -translate-y-1/2 flex-col overflow-hidden rounded-lg border border-border-default bg-bg-app shadow-2xl outline-none',
'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 duration-100',
className
)}
@@ -81,15 +88,20 @@ const Modal: React.FC<ModalProps> = ({
}}
>
{showHeader ? (
- <div className="relative flex w-full items-center border-b border-border bg-card px-5 py-3">
- <DialogTitle className="absolute left-5 flex items-center gap-2 text-base font-semibold text-foreground/80">
+ // Header: bg-bg-panel sits one elevation step above bg-bg-app
+ // (panel surface above page surface). font-display + tracking
+ // + text-transform are theme-driven so titles read as Cinzel
+ // uppercase under Renaissance and Major Mono Display under
+ // Cyber, while staying clean sans-serif under light/dark.
+ <div className="relative flex w-full items-center border-b border-border-default bg-bg-panel px-5 py-3">
+ <DialogTitle className="absolute left-5 flex items-center gap-2 font-display text-base font-semibold tracking-[var(--type-tracking-display)] text-fg-default [text-transform:var(--type-uppercase)]">
<Settings className="h-4 w-4 opacity-70" />
{title}
</DialogTitle>
<div className="flex flex-1 items-center justify-center">{headerActions}</div>
<DialogClose
onClick={onClose}
- className="absolute right-5 inline-flex h-8 w-8 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+ className="absolute right-5 inline-flex h-8 w-8 items-center justify-center rounded-md text-fg-muted transition-colors hover:bg-bg-hover hover:text-fg-default"
aria-label="Close"
>
<X className="h-[18px] w-[18px]" />
diff --git a/client/src/components/ui/SettingsPanel.tsx b/client/src/components/ui/SettingsPanel.tsx
index cac08c41..b342a37e 100644
--- a/client/src/components/ui/SettingsPanel.tsx
+++ b/client/src/components/ui/SettingsPanel.tsx
@@ -60,12 +60,17 @@ interface SectionProps {
}
const Section: React.FC<SectionProps> = ({ title, Icon, tone, children }) => (
- <div className="mb-4 rounded-md border border-border bg-muted p-4">
- <div className="mb-4 flex items-center gap-2 border-b border-border pb-3">
+ // bg-bg-elevated + border-default — settings sections are elevated
+ // cards stacked inside the modal body. font-display + tracking gives
+ // Renaissance/Cyber their typographic identity on section headers.
+ <div className="mb-4 rounded-md border border-border-default bg-bg-elevated p-4">
+ <div className="mb-4 flex items-center gap-2 border-b border-border-default pb-3">
<div className={`flex h-8 w-8 items-center justify-center rounded-md ${TONE_CLASSES[tone]}`}>
<Icon className="h-4 w-4" />
</div>
- <div className="text-base font-semibold text-foreground">{title}</div>
+ <div className="font-display text-base font-semibold tracking-[var(--type-tracking-display)] text-fg-default [text-transform:var(--type-uppercase)]">
+ {title}
+ </div>
</div>
{children}
</div>
@@ -80,8 +85,8 @@ interface RowProps {
const Row: React.FC<RowProps> = ({ label, description, children }) => (
<div className="flex items-center justify-between py-2">
<div className="flex-1">
- <div className="text-sm font-medium text-foreground">{label}</div>
- <div className="mt-0.5 text-xs text-muted-foreground">{description}</div>
+ <div className="text-sm font-medium text-fg-default">{label}</div>
+ <div className="mt-0.5 text-xs text-fg-muted">{description}</div>
</div>
{children}
</div>
@@ -149,7 +154,7 @@ const SettingsPanel: React.FC<SettingsPanelProps> = ({
const headerActions = (
<div className="flex items-center gap-4">
- <div className="flex items-center gap-2 text-[15px] font-semibold text-foreground">
+ <div className="flex items-center gap-2 font-display text-[15px] font-semibold tracking-[var(--type-tracking-display)] text-fg-default [text-transform:var(--type-uppercase)]">
<SettingsIcon className="h-4 w-4" />
<span>Settings</span>
</div>
@@ -266,7 +271,7 @@ const SettingsPanel: React.FC<SettingsPanelProps> = ({
disabled={isSaving}
className="pr-6"
/>
- <span className="pointer-events-none absolute top-1/2 right-2 -translate-y-1/2 text-xs text-muted-foreground">
+ <span className="pointer-events-none absolute top-1/2 right-2 -translate-y-1/2 text-xs text-fg-muted">
s
</span>
</div>
@@ -292,13 +297,13 @@ const SettingsPanel: React.FC<SettingsPanelProps> = ({
/>
</Row>
- <div className="my-1 border-b border-border" />
+ <div className="my-1 border-b border-border-default" />
<div className="py-2">
<div className="mb-2 flex items-center justify-between">
<div className="flex-1">
- <div className="text-sm font-medium text-foreground">Compaction Ratio</div>
- <div className="mt-0.5 text-xs text-muted-foreground">
+ <div className="text-sm font-medium text-fg-default">Compaction Ratio</div>
+ <div className="mt-0.5 text-xs text-fg-muted">
Fraction of context window that triggers memory compaction
</div>
</div>
@@ -315,12 +320,12 @@ const SettingsPanel: React.FC<SettingsPanelProps> = ({
disabled={isSaving}
className="my-3"
/>
- <div className="flex justify-between text-[10px] text-muted-foreground">
+ <div className="flex justify-between text-[10px] text-fg-muted">
<span>10%</span>
<span>50%</span>
<span>90%</span>
</div>
- <div className="mt-1 text-xs leading-snug text-muted-foreground">
+ <div className="mt-1 text-xs leading-snug text-fg-muted">
Lower = compact sooner (saves tokens, loses detail). Higher = compact later (preserves context, uses more tokens).
</div>
</div>
diff --git a/client/src/components/ui/StatusBar.tsx b/client/src/components/ui/StatusBar.tsx
new file mode 100644
index 00000000..fed21752
--- /dev/null
+++ b/client/src/components/ui/StatusBar.tsx
@@ -0,0 +1,95 @@
+/**
+ * StatusBar — fixed-bottom system console line.
+ *
+ * Lives below the canvas, shows workflow name, node count, WebSocket
+ * connection state, active theme, and a live clock. Designed to read
+ * as a "shell prompt" line under Cyber and a "manuscript footer" under
+ * Renaissance via the new-contract typography tokens (font-mono,
+ * tracking, uppercase).
+ *
+ * Per the handoff this is the `.statusbar` surface — it always exists,
+ * height is 24px, sits above the ConsolePanel toggle bar.
+ */
+
+import * as React from 'react';
+import { useEffect, useState } from 'react';
+import { useWebSocket } from '../../contexts/WebSocketContext';
+import { useTheme, type ThemeName } from '../../contexts/ThemeContext';
+import { cn } from '@/lib/utils';
+
+const THEME_LABEL: Record<ThemeName, string> = {
+ light: 'LIGHT',
+ dark: 'DARK',
+ renaissance: 'RENAISSANCE',
+ cyber: 'CYBER',
+};
+
+interface StatusBarProps {
+ workflowName?: string;
+ nodeCount?: number;
+}
+
+const useClock = (): string => {
+ const [time, setTime] = useState(() => new Date());
+ useEffect(() => {
+ const id = window.setInterval(() => setTime(new Date()), 1000);
+ return () => window.clearInterval(id);
+ }, []);
+ return time.toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false });
+};
+
+const Sep: React.FC = () => <span className="opacity-40">|</span>;
+
+export const StatusBar: React.FC<StatusBarProps> = ({ workflowName, nodeCount }) => {
+ const { isReady, isConnected } = useWebSocket();
+ const { theme } = useTheme();
+ const clock = useClock();
+
+ const wsStatus = isReady ? 'ONLINE' : isConnected ? 'CONNECTING' : 'OFFLINE';
+ const wsTone = isReady ? 'text-success' : isConnected ? 'text-warning' : 'text-destructive';
+
+ return (
+ // Fixed-bottom strip: bg-bg-panel + 1px top rule. font-mono carries
+ // through to IM Fell English under Renaissance and JetBrains Mono
+ // under Cyber, system mono under light/dark.
+ <div
+ className={cn(
+ 'flex h-6 items-center gap-3 border-t border-border-default bg-bg-panel px-3.5',
+ 'font-mono text-[11px] tracking-[0.04em] text-fg-muted',
+ '[text-transform:var(--type-uppercase)]',
+ )}
+ role="contentinfo"
+ aria-label="Status bar"
+ >
+ <span className={cn('flex items-center gap-1.5 font-medium', wsTone)}>
+ <span
+ className={cn(
+ 'inline-block h-1.5 w-1.5 rounded-full',
+ isReady ? 'bg-success animate-pulse' : isConnected ? 'bg-warning' : 'bg-destructive',
+ )}
+ />
+ {wsStatus}
+ </span>
+
+ <Sep />
+
+ <span title={workflowName ?? 'No workflow'}>
+ WF: <span className="text-fg-default">{workflowName ?? '—'}</span>
+ </span>
+
+ <Sep />
+
+ <span>NODES: <span className="text-fg-default">{nodeCount ?? 0}</span></span>
+
+ <span className="ml-auto flex items-center gap-3">
+ <span>
+ THEME: <span className="text-fg-default">{THEME_LABEL[theme]}</span>
+ </span>
+ <Sep />
+ <span className="tabular-nums">{clock}</span>
+ </span>
+ </div>
+ );
+};
+
+export default StatusBar;
diff --git a/client/src/components/ui/ThemeSwitcher.tsx b/client/src/components/ui/ThemeSwitcher.tsx
new file mode 100644
index 00000000..a495d7a3
--- /dev/null
+++ b/client/src/components/ui/ThemeSwitcher.tsx
@@ -0,0 +1,82 @@
+/**
+ * ThemeSwitcher — picks the active visual theme.
+ *
+ * Renders one DropdownMenu item per theme listed in `AVAILABLE_THEMES`.
+ * Selection persists via ThemeContext (localStorage `machinaos-theme`).
+ *
+ * Adding a new theme: drop a CSS file under client/src/themes/, import
+ * it in main.tsx, add the name to `AVAILABLE_THEMES` in ThemeContext.
+ * This component picks it up automatically; no edits here.
+ */
+
+import * as React from 'react';
+import { Check, Palette } from 'lucide-react';
+import {
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuLabel,
+ DropdownMenuSeparator,
+ DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { Button } from '@/components/ui/button';
+import { useTheme, type ThemeName } from '../../contexts/ThemeContext';
+
+interface ThemeMeta {
+ label: string;
+ blurb: string;
+}
+
+const THEME_META: Record<ThemeName, ThemeMeta> = {
+ light: { label: 'Light', blurb: 'Clean default' },
+ dark: { label: 'Dark', blurb: 'Solarized + Dracula' },
+ renaissance: { label: 'Renaissance', blurb: 'Illuminated codex' },
+ cyber: { label: 'Cyber-Tyranny', blurb: 'Neon night market' },
+};
+
+export const ThemeSwitcher: React.FC<{ className?: string }> = ({ className }) => {
+ const { theme, setTheme, availableThemes } = useTheme();
+ const activeMeta = THEME_META[theme];
+
+ return (
+ <DropdownMenu>
+ <DropdownMenuTrigger asChild>
+ <Button
+ variant="outline"
+ size="icon-sm"
+ title={`Theme: ${activeMeta.label}`}
+ className="border-action-secret-border bg-action-secret-soft text-action-secret hover:bg-action-secret/25"
+ >
+ <Palette />
+ </Button>
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="end" className={className ?? 'min-w-[220px]'}>
+ <DropdownMenuLabel className="text-xs uppercase tracking-wider text-muted-foreground">
+ Theme
+ </DropdownMenuLabel>
+ <DropdownMenuSeparator />
+ {availableThemes.map((name) => {
+ const meta = THEME_META[name];
+ const isActive = name === theme;
+ return (
+ <DropdownMenuItem
+ key={name}
+ onSelect={() => setTheme(name)}
+ className="flex items-center gap-2"
+ >
+ <span className="flex h-4 w-4 items-center justify-center">
+ {isActive && <Check className="h-3.5 w-3.5" />}
+ </span>
+ <span className="flex-1">
+ <span className="block text-sm font-medium">{meta.label}</span>
+ <span className="block text-[11px] text-muted-foreground">{meta.blurb}</span>
+ </span>
+ </DropdownMenuItem>
+ );
+ })}
+ </DropdownMenuContent>
+ </DropdownMenu>
+ );
+};
+
+export default ThemeSwitcher;
diff --git a/client/src/components/ui/TopToolbar.tsx b/client/src/components/ui/TopToolbar.tsx
index 457d4fb3..94ed62f2 100644
--- a/client/src/components/ui/TopToolbar.tsx
+++ b/client/src/components/ui/TopToolbar.tsx
@@ -14,8 +14,6 @@ import {
Pencil,
Settings as SettingsIcon,
KeyRound,
- Sun,
- Moon,
LogOut,
Save,
Play,
@@ -43,14 +41,17 @@ import {
} from '@/components/ui/dropdown-menu';
import { Button } from '@/components/ui/button';
import { ActionButton } from '@/components/ui/action-button';
+import { ThemeSwitcher } from '@/components/ui/ThemeSwitcher';
import { cn } from '@/lib/utils';
-import { useTheme } from '../../contexts/ThemeContext';
import { useAuth } from '../../contexts/AuthContext';
import { useApiKeys, GlobalModelState } from '../../hooks/useApiKeys';
import { useStoredProviderCount } from '../../hooks/useCatalogueQuery';
import { AI_PROVIDER_META } from '../icons/AIProviderIcons';
-const Divider = () => <div className="mx-1 h-6 w-px bg-border" />;
+// New-contract token: --border-default ↔ Tailwind utility `bg-border-default`.
+// Same colour as `bg-border` under light/dark, retints automatically under
+// renaissance / cyber via the per-theme [data-theme="..."] block.
+const Divider = () => <div className="mx-1 h-6 w-px bg-border-default" />;
interface TopToolbarProps {
workflowName: string;
@@ -107,7 +108,6 @@ const TopToolbar: React.FC<TopToolbarProps> = ({
}) => {
const [isEditing, setIsEditing] = useState(false);
const [tempName, setTempName] = useState(workflowName);
- const { isDarkMode, toggleTheme } = useTheme();
const { user, logout } = useAuth();
// Global Model Selector state
@@ -155,7 +155,11 @@ const TopToolbar: React.FC<TopToolbarProps> = ({
};
return (
- <div className="flex h-12 items-center justify-between gap-3 border-b border-border bg-muted px-3">
+ // border-default + bg-bg-panel are the new-contract tokens. They
+ // resolve to the existing colours under light/dark (no visual
+ // change) but pick up the parchment / void surfaces under
+ // renaissance / cyber automatically.
+ <div className="flex h-12 items-center justify-between gap-3 border-b border-border-default bg-bg-panel px-3">
{/* ---------- Left Section ---------- */}
<div className="flex items-center gap-1.5">
<Button
@@ -180,7 +184,13 @@ const TopToolbar: React.FC<TopToolbarProps> = ({
className="border-action-save-border bg-action-save-soft text-action-save hover:bg-action-save/25"
>
<FileText />
- File
+ {/* font-display + tracking-display drive the per-theme display
+ font + letter-spacing; uppercase is gated by --type-uppercase
+ via the new-contract `tracking-display` token (light/dark
+ use 0 + none, renaissance + cyber turn it on). */}
+ <span className="font-display tracking-[var(--type-tracking-display)] [text-transform:var(--type-uppercase)]">
+ File
+ </span>
<ChevronDown />
</Button>
</DropdownMenuTrigger>
@@ -230,10 +240,17 @@ const TopToolbar: React.FC<TopToolbarProps> = ({
<button
onClick={handleNameClick}
title="Click to rename"
- className="flex items-center gap-1.5 rounded-sm bg-transparent px-3 py-1.5 transition-colors hover:bg-card"
+ className="flex items-center gap-1.5 rounded-sm bg-transparent px-3 py-1.5 transition-colors hover:bg-bg-hover"
>
- <span className="text-sm font-medium text-node-agent">{workflowName}</span>
- <Pencil className="h-3 w-3 text-muted-foreground" />
+ {/* font-display + tracking-display + [text-transform] are
+ theme-driven via the new-contract typography tokens. Under
+ light/dark the workflow name reads as our regular sans-serif;
+ under Renaissance it becomes Cinzel uppercase, under Cyber it
+ becomes Major Mono Display uppercase. */}
+ <span className="text-sm font-display font-medium tracking-[var(--type-tracking-display)] text-fg-default [text-transform:var(--type-uppercase)]">
+ {workflowName}
+ </span>
+ <Pencil className="h-3 w-3 text-fg-muted" />
</button>
)}
</div>
@@ -354,15 +371,7 @@ const TopToolbar: React.FC<TopToolbarProps> = ({
<KeyRound />
</Button>
- <Button
- variant="outline"
- size="icon-sm"
- onClick={toggleTheme}
- title={isDarkMode ? 'Switch to Light mode' : 'Switch to Dark mode'}
- className="border-action-secret-border bg-action-secret-soft text-action-secret hover:bg-action-secret/25"
- >
- {isDarkMode ? <Sun /> : <Moon />}
- </Button>
+ <ThemeSwitcher />
{user && (
<Button
@@ -410,10 +419,12 @@ const TopToolbar: React.FC<TopToolbarProps> = ({
Save
</ActionButton>
- {/* Status Indicator */}
+ {/* Status Indicator — font-mono tracks the new-contract --font-mono
+ so renaissance gets IM Fell English and cyber gets JetBrains
+ Mono. Stays system mono under light/dark. */}
<div
className={cn(
- 'flex items-center gap-2 rounded-sm px-3 py-1 text-xs font-medium',
+ 'flex items-center gap-2 rounded-sm px-3 py-1 text-xs font-mono',
hasUnsavedChanges ? 'text-warning' : 'text-success'
)}
>
diff --git a/client/src/components/ui/WorkflowSidebar.tsx b/client/src/components/ui/WorkflowSidebar.tsx
index de880316..6abb57ec 100644
--- a/client/src/components/ui/WorkflowSidebar.tsx
+++ b/client/src/components/ui/WorkflowSidebar.tsx
@@ -40,13 +40,16 @@ const WorkflowCard: React.FC<WorkflowCardProps> = ({
onSelect,
onDelete,
}) => (
+ // Card: bg-bg-app (page-level surface, sits below panel chrome) +
+ // border-default. Selected state lifts to bg-bg-active and gains a
+ // 3px accent left edge — matches handoff `.wf-card.selected`.
<Card
onClick={onSelect}
className={cn(
- 'group relative mb-2 cursor-pointer p-3 transition-colors',
+ 'group relative mb-2 cursor-pointer border-border-default bg-bg-app p-3 transition-colors',
isSelected
- ? 'border-accent border-l-[3px] bg-accent/10'
- : 'hover:bg-muted'
+ ? 'border-accent border-l-[3px] bg-bg-active'
+ : 'hover:bg-bg-hover'
)}
>
<div className="mb-1 flex items-center gap-2">
@@ -55,25 +58,29 @@ const WorkflowCard: React.FC<WorkflowCardProps> = ({
'flex h-6 w-6 shrink-0 items-center justify-center rounded-sm border',
isSelected
? 'border-accent bg-accent/20 text-accent'
- : 'border-border bg-muted text-muted-foreground'
+ : 'border-border-default bg-bg-elevated text-fg-muted'
)}
>
<Code2 className="h-3 w-3" />
</div>
<h4
className={cn(
- 'm-0 flex-1 truncate text-sm font-medium',
- isSelected ? 'text-accent' : 'text-foreground'
+ // Display typography on the workflow name — Cinzel under
+ // Renaissance, Major Mono Display under Cyber.
+ 'm-0 flex-1 truncate font-display text-sm font-medium tracking-[var(--type-tracking-display)] [text-transform:var(--type-uppercase)]',
+ isSelected ? 'text-accent' : 'text-fg-default'
)}
>
{workflow.name}
</h4>
</div>
+ {/* Metadata uses font-mono — picks up IM Fell English / JetBrains
+ Mono / system mono per theme. */}
<div
className={cn(
- 'flex items-center justify-between text-xs',
- isSelected ? 'text-foreground' : 'text-muted-foreground'
+ 'flex items-center justify-between font-mono text-xs',
+ isSelected ? 'text-fg-default' : 'text-fg-muted'
)}
>
<span>{workflow.nodeCount} nodes</span>
@@ -106,16 +113,21 @@ const WorkflowSidebar: React.FC<WorkflowSidebarProps> = ({
onDeleteWorkflow,
}) => {
return (
- <div className="flex h-full w-[280px] flex-col overflow-hidden border-r border-border bg-card">
- {/* Header */}
- <div className="border-b border-border bg-muted px-4 py-5">
+ // Sidebar shell: bg-bg-panel matches the handoff `.sidebar` token.
+ <div className="flex h-full w-[280px] flex-col overflow-hidden border-r border-border-default bg-bg-panel">
+ {/* Header — bg-bg-app drops one elevation step below the panel
+ chrome, giving the heading area a subtle "page" backdrop
+ that's distinct from the card list. */}
+ <div className="border-b border-border-default bg-bg-app px-4 py-5">
<div className="flex items-center gap-2">
<div className="flex h-9 w-9 items-center justify-center rounded-md bg-accent/20 text-accent">
<FolderOpen className="h-4 w-4" />
</div>
<div>
- <h3 className="m-0 text-base font-semibold text-foreground">Workflows</h3>
- <p className="m-0 text-xs text-muted-foreground">{workflows.length} saved</p>
+ <h3 className="m-0 font-display text-base font-semibold tracking-[var(--type-tracking-display)] text-fg-default [text-transform:var(--type-uppercase)]">
+ Workflows
+ </h3>
+ <p className="m-0 font-mono text-xs text-fg-muted">{workflows.length} saved</p>
</div>
</div>
</div>
@@ -123,11 +135,11 @@ const WorkflowSidebar: React.FC<WorkflowSidebarProps> = ({
{/* List */}
<div className="flex-1 overflow-y-auto p-3">
{workflows.length === 0 ? (
- <div className="px-4 py-12 text-center text-sm text-muted-foreground">
- <div className="mx-auto mb-4 flex h-16 w-16 items-center justify-center rounded-lg border-2 border-dashed border-border bg-muted">
+ <div className="px-4 py-12 text-center text-sm text-fg-muted">
+ <div className="mx-auto mb-4 flex h-16 w-16 items-center justify-center rounded-lg border-2 border-dashed border-border-default bg-bg-elevated">
<FilePlus className="h-7 w-7 stroke-1" />
</div>
- <p className="m-0 font-medium text-foreground">No workflows yet</p>
+ <p className="m-0 font-medium text-fg-default">No workflows yet</p>
<p className="mt-2 text-xs leading-relaxed">
Create your first workflow<br />to get started
</p>
diff --git a/client/src/contexts/ThemeContext.tsx b/client/src/contexts/ThemeContext.tsx
index b35e7262..fd681b14 100644
--- a/client/src/contexts/ThemeContext.tsx
+++ b/client/src/contexts/ThemeContext.tsx
@@ -1,36 +1,100 @@
-import React, { createContext, useContext, useState, useEffect } from 'react';
+/**
+ * ThemeContext — owns the active visual theme.
+ *
+ * Themes are resolved entirely in CSS via `:root[data-theme="<name>"]`
+ * scoped blocks under client/src/themes/. This provider's only job is
+ * to write the chosen name to `<html data-theme>` (and the legacy
+ * `<html class="dark">` flag for any `dark:` Tailwind variants still
+ * in use), persist the choice to localStorage, and migrate legacy
+ * callers reading `isDarkMode` / `toggleTheme`.
+ *
+ * Adding a new theme: drop a new CSS file under client/src/themes/
+ * scoped to `:root[data-theme="<name>"]`, import it in main.tsx, and
+ * add the name to `AVAILABLE_THEMES` below.
+ */
+
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';
+
+export type ThemeName = 'light' | 'dark' | 'renaissance' | 'cyber';
+
+export const AVAILABLE_THEMES: readonly ThemeName[] = ['light', 'dark', 'renaissance', 'cyber'];
+
+const THEME_STORAGE_KEY = 'machinaos-theme';
+const LEGACY_DARK_MODE_KEY = 'darkMode';
+
+/** Themes that should also flip the legacy `.dark` Tailwind variant on. */
+const DARK_FAMILY: ReadonlySet<ThemeName> = new Set(['dark', 'cyber']);
interface ThemeContextType {
+ theme: ThemeName;
+ setTheme: (t: ThemeName) => void;
+ availableThemes: readonly ThemeName[];
+ /** Backwards-compat: true for dark + cyber. */
isDarkMode: boolean;
+ /** Backwards-compat: rotates light <-> dark only (preserves legacy callers). */
toggleTheme: () => void;
}
const ThemeContext = createContext<ThemeContextType | undefined>(undefined);
+function isThemeName(value: string | null | undefined): value is ThemeName {
+ return !!value && (AVAILABLE_THEMES as readonly string[]).includes(value);
+}
+
+function loadInitialTheme(): ThemeName {
+ // 1. Honour the new key first.
+ const stored = localStorage.getItem(THEME_STORAGE_KEY);
+ if (isThemeName(stored)) return stored;
+
+ // 2. Migrate the legacy `darkMode` boolean key (was 'true' / 'false' / null).
+ const legacy = localStorage.getItem(LEGACY_DARK_MODE_KEY);
+ if (legacy !== null) {
+ const migrated: ThemeName = legacy === 'false' ? 'light' : 'dark';
+ localStorage.setItem(THEME_STORAGE_KEY, migrated);
+ localStorage.removeItem(LEGACY_DARK_MODE_KEY);
+ return migrated;
+ }
+
+ // 3. First-launch default — match the previous default of `isDarkMode: true`.
+ return 'dark';
+}
+
export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
- const [isDarkMode, setIsDarkMode] = useState(() => {
- const saved = localStorage.getItem('darkMode');
- return saved === null ? true : saved === 'true';
- });
+ const [theme, setThemeState] = useState<ThemeName>(loadInitialTheme);
useEffect(() => {
- localStorage.setItem('darkMode', isDarkMode.toString());
- if (isDarkMode) {
- document.documentElement.classList.add('dark');
+ const html = document.documentElement;
+ html.dataset.theme = theme;
+ if (DARK_FAMILY.has(theme)) {
+ html.classList.add('dark');
} else {
- document.documentElement.classList.remove('dark');
+ html.classList.remove('dark');
}
- }, [isDarkMode]);
+ localStorage.setItem(THEME_STORAGE_KEY, theme);
+ }, [theme]);
+
+ const setTheme = useCallback((next: ThemeName) => {
+ setThemeState(next);
+ }, []);
- const toggleTheme = () => {
- setIsDarkMode(prev => !prev);
- };
+ const toggleTheme = useCallback(() => {
+ // Legacy semantics: bounce between light and dark only. Renaissance /
+ // Cyber are reachable through `setTheme` / `<ThemeSwitcher>` instead.
+ setThemeState((prev) => (prev === 'dark' ? 'light' : 'dark'));
+ }, []);
- return (
- <ThemeContext.Provider value={{ isDarkMode, toggleTheme }}>
- {children}
- </ThemeContext.Provider>
+ const value = useMemo<ThemeContextType>(
+ () => ({
+ theme,
+ setTheme,
+ availableThemes: AVAILABLE_THEMES,
+ isDarkMode: DARK_FAMILY.has(theme),
+ toggleTheme,
+ }),
+ [theme, setTheme, toggleTheme],
);
+
+ return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
};
export const useTheme = () => {
diff --git a/client/src/index.css b/client/src/index.css
index 7a834e6a..dfc55d86 100644
--- a/client/src/index.css
+++ b/client/src/index.css
@@ -301,6 +301,49 @@
--font-sans: 'Geist Variable', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
--font-mono: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Monaco, Consolas, monospace;
+
+ /* ── New-contract tokens (design_handoff_machinaos_themes) ──────────
+ * Surface / foreground / semantic / typography / radius tokens
+ * exposed as Tailwind utilities. Defined per-theme in client/src/
+ * themes/{light,dark,renaissance,cyber}.css — themes redefine the
+ * `--bg-app`, `--fg-default`, etc. CSS variables under
+ * `:root[data-theme="..."]`; these `@theme inline` aliases give
+ * Tailwind classes that resolve against whichever theme is active.
+ *
+ * Note: full-colour values (not HSL triplets), so `bg-bg-app/50`
+ * alpha composition does NOT work — use `--bg-overlay` or the
+ * shadcn alias (`bg-background/50`) when you need alpha. */
+ --color-bg-app: var(--bg-app);
+ --color-bg-panel: var(--bg-panel);
+ --color-bg-canvas: var(--bg-canvas);
+ --color-bg-elevated: var(--bg-elevated);
+ --color-bg-input: var(--bg-input);
+ --color-bg-hover: var(--bg-hover);
+ --color-bg-active: var(--bg-active);
+ --color-bg-overlay: var(--bg-overlay);
+
+ --color-fg-default: var(--fg-default);
+ --color-fg-muted: var(--fg-muted);
+ --color-fg-faint: var(--fg-faint);
+ --color-fg-on-accent: var(--fg-on-accent);
+ --color-fg-on-success: var(--fg-on-success);
+ --color-fg-on-danger: var(--fg-on-danger);
+ --color-fg-on-warning: var(--fg-on-warning);
+
+ /* Border tokens — exposed as Tailwind colour utilities so call sites
+ * can write `border-default`, `border-strong`, `border-focus` /
+ * `bg-border-default` etc. */
+ --color-border-default: var(--border-default);
+ --color-border-strong: var(--border-strong);
+ --color-border-focus: var(--border-focus);
+
+ /* Typography family aliases — `font-display`, `font-body` (font-mono
+ * is already exposed above; we re-declare it here so it tracks the
+ * per-theme `--font-mono` instead of the static fallback). */
+ --font-display: var(--font-display);
+ --font-body: var(--font-body);
+
+ --radius-pill: var(--radius-pill);
}
/* ============================================================================
diff --git a/client/src/main.tsx b/client/src/main.tsx
index 959ba2c2..789c446c 100644
--- a/client/src/main.tsx
+++ b/client/src/main.tsx
@@ -2,6 +2,16 @@ import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+// Theme CSS — load BEFORE index.css so the per-theme [data-theme="..."]
+// blocks register their tokens before Tailwind compiles `@theme inline`
+// against the cascade. Order within the theme list matches specificity:
+// base.css (neutral defaults) → light.css (default :root + [data-theme="light"])
+// → dark.css (.dark + [data-theme="dark"]) → renaissance + cyber overrides.
+import './themes/base.css'
+import './themes/light.css'
+import './themes/dark.css'
+import './themes/renaissance.css'
+import './themes/cyber.css'
import './index.css'
import App from './App'
import { ThemeProvider } from './contexts/ThemeContext'
diff --git a/client/src/themes/base.css b/client/src/themes/base.css
new file mode 100644
index 00000000..f68e08e0
--- /dev/null
+++ b/client/src/themes/base.css
@@ -0,0 +1,45 @@
+/* ============================================================================
+ * themes/base.css — neutral defaults shared by every theme.
+ *
+ * These are scoped to :root (no data-theme selector) so they apply as
+ * fallbacks when a theme block omits the variable. Per-theme blocks
+ * always win via specificity (`:root[data-theme="..."]` beats `:root`).
+ *
+ * Source: design_handoff_machinaos_themes/themes/base.css.
+ * ============================================================================ */
+
+:root {
+ /* Space scale (4 / 8 / 12 / 16 / 24 / 32 / 48 / 64) */
+ --space-1: 4px;
+ --space-2: 8px;
+ --space-3: 12px;
+ --space-4: 16px;
+ --space-5: 24px;
+ --space-6: 32px;
+ --space-7: 48px;
+ --space-8: 64px;
+
+ /* New-contract radii — exposed as Tailwind tokens via index.css.
+ * Co-exist with shadcn `--radius` (still used by existing primitives). */
+ --radius-pill: 999px;
+
+ /* Motion */
+ --dur-fast: 90ms;
+ --dur-default: 180ms;
+ --dur-slow: 320ms;
+ --ease-default: cubic-bezier(0.2, 0.7, 0.3, 1);
+ --ease-emphasis: cubic-bezier(0.6, -0.05, 0.3, 1.4);
+ --motion-style: smooth;
+
+ /* Sound (read by JS in a future phase) */
+ --sound-pack: none;
+
+ /* Type case toggle — themes flip between `none` / `uppercase` / `capitalize`. */
+ --type-uppercase: none;
+ --type-tracking-display: 0;
+ --type-scale-base: 14px;
+
+ /* Cursor + scrollbar */
+ --cursor-default: auto;
+ --cursor-pointer: pointer;
+}
diff --git a/client/src/themes/cyber.css b/client/src/themes/cyber.css
new file mode 100644
index 00000000..33f9dce6
--- /dev/null
+++ b/client/src/themes/cyber.css
@@ -0,0 +1,164 @@
+/* ============================================================================
+ * themes/cyber.css — Neuromancer night market / pirated terminal popup.
+ *
+ * Defines the full new-contract token block AND overrides the shadcn
+ * HSL-triplet tokens so existing Tailwind utilities retint correctly.
+ *
+ * Palette: void (#050010), neon magenta (#f51eb6), neon cyan (#1dd9e5),
+ * neon green (#26d97a). HSL triplets are conversions of the same hex
+ * values.
+ *
+ * Decorative layers (scanlines, CRT flicker, grid backplane, neon glow)
+ * are deferred to Phase 3 fan-out.
+ *
+ * Source: design_handoff_machinaos_themes/themes/cyber.css.
+ * ============================================================================ */
+
+:root[data-theme="cyber"] {
+ /* ── New contract — full colour values ────────────────────────────── */
+
+ /* Surfaces */
+ --bg-app: #050010;
+ --bg-panel: #0a0420;
+ --bg-canvas: #03000a;
+ --bg-elevated: #15103a;
+ --bg-input: #0a0420;
+ --bg-hover: rgba(245, 30, 182, 0.14);
+ --bg-active: rgba(245, 30, 182, 0.20);
+ --bg-overlay: rgba(5, 0, 16, 0.85);
+
+ /* Borders */
+ --border-default: #2a1f50;
+ --border-strong: #f51eb6;
+ --border-focus: #1dd9e5;
+ --ornament-frame: none;
+
+ /* Foreground */
+ --fg-default: #f0e0ff;
+ --fg-muted: #a090c0;
+ --fg-faint: #6a5a8a;
+ --fg-on-accent: #050010;
+ --fg-on-success: #050010;
+ --fg-on-danger: #f5e0ea;
+ --fg-on-warning: #050010;
+
+ /* Theme-specific neon accents */
+ --neon-cyan: #1dd9e5;
+ --neon-magenta: #f51eb6;
+ --neon-yellow: #ffd028;
+ --neon-green: #26d97a;
+
+ /* Type — Major Mono Display + JetBrains Mono everywhere */
+ --font-display: 'Major Mono Display', 'Audiowide', monospace;
+ --font-body: 'JetBrains Mono', 'Fira Code', ui-monospace, monospace;
+ --font-mono: 'JetBrains Mono', monospace;
+ --type-scale-base: 13px;
+ --type-tracking-display: 0.18em;
+ --type-uppercase: uppercase;
+
+ /* Geometry — sharp corners everywhere */
+ --radius-sm: 0;
+ --radius-md: 0;
+ --radius-lg: 0;
+ --radius-pill: 0;
+
+ /* Motion — fast, mechanical (steps easing for hard on/off) */
+ --ease-default: steps(4, end);
+ --ease-emphasis: steps(8, end);
+ --dur-fast: 60ms;
+ --dur-default: 120ms;
+ --dur-slow: 240ms;
+ --motion-style: glitch;
+ --sound-pack: terminal;
+
+ /* Cursor + scrollbar */
+ --cursor-default: auto;
+ --cursor-pointer: pointer;
+ --scrollbar-track: #0a0420;
+ --scrollbar-thumb: #f51eb6;
+
+ /* ── Shadcn HSL-triplet bridge ───────────────────────────────────── */
+
+ --background: 247 100% 4%; /* #050010 */
+ --foreground: 267 100% 94%; /* #f0e0ff */
+ --card: 247 57% 15%; /* #15103a */
+ --card-foreground: 267 100% 94%;
+ --popover: 253 80% 7%; /* #0a0420 */
+ --popover-foreground: 267 100% 94%;
+
+ --primary: 316 92% 54%; /* #f51eb6 neon magenta */
+ --primary-foreground: 247 100% 4%;
+ --secondary: 253 80% 7%; /* panel */
+ --secondary-foreground: 267 100% 94%;
+ --muted: 253 80% 7%;
+ --muted-foreground: 260 25% 66%; /* #a090c0 */
+ --accent: 184 79% 51%; /* #1dd9e5 neon cyan */
+ --accent-foreground: 247 100% 4%;
+
+ --destructive: 347 100% 56%; /* #ff2050 */
+ --destructive-foreground: 0 0% 100%;
+ --success: 147 71% 50%; /* #26d97a neon green */
+ --warning: 46 100% 58%; /* #ffd028 neon yellow */
+ --info: 184 79% 51%; /* neon cyan */
+
+ --border: 253 44% 22%; /* #2a1f50 */
+ --input: 253 44% 22%;
+ --ring: 184 79% 51%; /* cyan focus */
+
+ /* Action role tokens — neon equivalents */
+ --action-run: 147 71% 50%; /* neon green */
+ --action-run-soft: 147 71% 50% / 0.15;
+ --action-run-hover: 147 71% 50% / 0.30;
+ --action-run-border: 147 71% 50% / 0.7;
+
+ --action-stop: 347 100% 56%; /* danger red */
+ --action-stop-soft: 347 100% 56% / 0.15;
+ --action-stop-hover: 347 100% 56% / 0.30;
+ --action-stop-border: 347 100% 56% / 0.7;
+
+ --action-save: 184 79% 51%; /* neon cyan */
+ --action-save-soft: 184 79% 51% / 0.15;
+ --action-save-hover: 184 79% 51% / 0.30;
+ --action-save-border: 184 79% 51% / 0.7;
+
+ --action-config: 46 100% 58%; /* neon yellow */
+ --action-config-soft: 46 100% 58% / 0.15;
+ --action-config-hover: 46 100% 58% / 0.30;
+ --action-config-border: 46 100% 58% / 0.7;
+
+ --action-secret: 316 92% 54%; /* neon magenta */
+ --action-secret-soft: 316 92% 54% / 0.15;
+ --action-secret-hover: 316 92% 54% / 0.30;
+ --action-secret-border: 316 92% 54% / 0.7;
+
+ --action-tools: 316 92% 54%; /* magenta */
+ --action-tools-soft: 316 92% 54% / 0.15;
+ --action-tools-hover: 316 92% 54% / 0.30;
+ --action-tools-border: 316 92% 54% / 0.7;
+
+ /* Stronger tint alpha — neon brand colours need more presence on void */
+ --tint-soft: 16%;
+ --tint-border: 50%;
+}
+
+/* ── Body void background ────────────────────────────────────────────── */
+
+:root[data-theme="cyber"] body {
+ background:
+ radial-gradient(ellipse at 20% 30%, rgba(245, 30, 182, 0.12), transparent 40%),
+ radial-gradient(ellipse at 80% 70%, rgba(29, 217, 229, 0.08), transparent 40%),
+ url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='400' height='400'><filter id='n'><feTurbulence baseFrequency='2' numOctaves='1' seed='3'/><feColorMatrix values='0 0 0 0 1 0 0 0 0 0.4 0 0 0 0 1 0 0 0 0.04 0'/></filter><rect width='400' height='400' filter='url(%23n)'/></svg>"),
+ var(--bg-app);
+}
+
+/* ::selection — neon highlight */
+:root[data-theme="cyber"] ::selection {
+ background: #f51eb6;
+ color: #050010;
+}
+
+/* Cyber scrollbars — neon thumbs with glow */
+:root[data-theme="cyber"] ::-webkit-scrollbar-thumb {
+ background: #f51eb6;
+ box-shadow: 0 0 6px #f51eb6;
+}
diff --git a/client/src/themes/dark.css b/client/src/themes/dark.css
new file mode 100644
index 00000000..0fc81f7d
--- /dev/null
+++ b/client/src/themes/dark.css
@@ -0,0 +1,70 @@
+/* ============================================================================
+ * themes/dark.css — dark theme new-contract tokens.
+ *
+ * Scoped to BOTH `.dark` (so existing Tailwind `dark:` variants and the
+ * legacy `<html class="dark">` toggle continue to work) AND
+ * `:root[data-theme="dark"]` (the explicit theme name).
+ *
+ * Mirrors the existing `.dark` block in index.css for shadcn HSL-triplet
+ * tokens; this file only adds the new full-colour contract.
+ *
+ * Source palette: Solarized dark + Dracula accents (matches existing
+ * dark theme in client/src/styles/theme.ts).
+ * ============================================================================ */
+
+.dark,
+:root[data-theme="dark"] {
+ /* Surfaces — Solarized dark base + Dracula highlights */
+ --bg-app: #002b36; /* base03 */
+ --bg-panel: #073642; /* base02 */
+ --bg-canvas: #002b36;
+ --bg-elevated: #0d1f2d;
+ --bg-input: #073642;
+ --bg-hover: rgba(248, 248, 242, 0.06);
+ --bg-active: rgba(189, 147, 249, 0.18);
+ --bg-overlay: rgba(0, 0, 0, 0.7);
+
+ /* Borders */
+ --border-default: #586e75; /* base01 */
+ --border-strong: #93a1a1;
+ --border-focus: #268bd2; /* solarized blue */
+ --ornament-frame: none;
+
+ /* Foreground — Dracula light foreground for readability over Solarized dark */
+ --fg-default: #f8f8f2;
+ --fg-muted: #6272a4; /* dracula comment */
+ --fg-faint: #586e75;
+ --fg-on-accent: #002b36;
+ --fg-on-success: #002b36;
+ --fg-on-danger: #f8f8f2;
+ --fg-on-warning: #002b36;
+
+ /* Type — same as light (system stack) */
+ --font-display: 'Geist Variable', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+ --font-body: 'Geist Variable', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+ --font-mono: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Monaco, Consolas, monospace;
+ --type-scale-base: 14px;
+ --type-tracking-display: 0;
+ --type-uppercase: none;
+
+ /* Geometry — same scale as light */
+ --radius-sm: 4px;
+ --radius-md: 6px;
+ --radius-lg: 8px;
+ --radius-pill: 999px;
+
+ /* Motion */
+ --dur-fast: 90ms;
+ --dur-default: 180ms;
+ --dur-slow: 320ms;
+ --ease-default: cubic-bezier(0.2, 0.7, 0.3, 1);
+ --ease-emphasis: cubic-bezier(0.6, -0.05, 0.3, 1.4);
+ --motion-style: smooth;
+ --sound-pack: chime;
+
+ /* Cursor + scrollbar */
+ --cursor-default: auto;
+ --cursor-pointer: pointer;
+ --scrollbar-track: #073642;
+ --scrollbar-thumb: #586e75;
+}
diff --git a/client/src/themes/light.css b/client/src/themes/light.css
new file mode 100644
index 00000000..df557312
--- /dev/null
+++ b/client/src/themes/light.css
@@ -0,0 +1,78 @@
+/* ============================================================================
+ * themes/light.css — light theme new-contract tokens.
+ *
+ * Mirrors the existing :root block in index.css (which still owns the
+ * shadcn HSL-triplet tokens). This file ADDS the new full-colour
+ * contract — surface / foreground / accent / typography / motion —
+ * scoped to `:root[data-theme="light"]` AND the unscoped `:root` so
+ * the contract is satisfied even when no data-theme attribute is set.
+ *
+ * Existing Tailwind utilities (bg-card, text-foreground, border-border,
+ * bg-action-save-soft, etc.) keep working unchanged because the shadcn
+ * tokens stay live in index.css.
+ *
+ * New utilities exposed by index.css `@theme inline`:
+ * bg-bg-app, bg-bg-panel, bg-bg-elevated, bg-bg-canvas, bg-bg-input,
+ * bg-bg-hover, bg-bg-active, bg-bg-overlay,
+ * text-fg-default, text-fg-muted, text-fg-faint, text-fg-on-accent,
+ * border-default, border-strong, border-focus,
+ * font-display, font-body (font-mono comes from index.css),
+ * tracking-display, rounded-pill.
+ * ============================================================================ */
+
+:root,
+:root[data-theme="light"] {
+ /* Surfaces (light mode — light grey palette consistent with existing values) */
+ --bg-app: #f5f7fa;
+ --bg-panel: #fafbfc;
+ --bg-canvas: #ffffff;
+ --bg-elevated: #ffffff;
+ --bg-input: #ffffff;
+ --bg-hover: rgba(0, 0, 0, 0.04);
+ --bg-active: rgba(0, 0, 0, 0.06);
+ --bg-overlay: rgba(0, 0, 0, 0.45);
+
+ /* Borders */
+ --border-default: #d1d5db;
+ --border-strong: #9ca3af;
+ --border-focus: #3b82f6;
+ --ornament-frame: none;
+
+ /* Foreground */
+ --fg-default: #1a1d21;
+ --fg-muted: #4b5563;
+ --fg-faint: #9ca3af;
+ --fg-on-accent: #ffffff;
+ --fg-on-success: #ffffff;
+ --fg-on-danger: #ffffff;
+ --fg-on-warning: #1a1d21;
+
+ /* Type — system stack for light/dark; Renaissance + Cyber override */
+ --font-display: 'Geist Variable', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+ --font-body: 'Geist Variable', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+ --font-mono: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Monaco, Consolas, monospace;
+ --type-scale-base: 14px;
+ --type-tracking-display: 0;
+ --type-uppercase: none;
+
+ /* Geometry — match existing shadcn radius (0.5rem / 8px) */
+ --radius-sm: 4px;
+ --radius-md: 6px;
+ --radius-lg: 8px;
+ --radius-pill: 999px;
+
+ /* Motion — match base defaults (smooth) */
+ --dur-fast: 90ms;
+ --dur-default: 180ms;
+ --dur-slow: 320ms;
+ --ease-default: cubic-bezier(0.2, 0.7, 0.3, 1);
+ --ease-emphasis: cubic-bezier(0.6, -0.05, 0.3, 1.4);
+ --motion-style: smooth;
+ --sound-pack: chime;
+
+ /* Cursor + scrollbar */
+ --cursor-default: auto;
+ --cursor-pointer: pointer;
+ --scrollbar-track: #eef1f5;
+ --scrollbar-thumb: #d1d5db;
+}
diff --git a/client/src/themes/renaissance.css b/client/src/themes/renaissance.css
new file mode 100644
index 00000000..f512eec1
--- /dev/null
+++ b/client/src/themes/renaissance.css
@@ -0,0 +1,171 @@
+/* ============================================================================
+ * themes/renaissance.css — illuminated codex / Florentine workshop manuscript.
+ *
+ * Defines the full new-contract token block AND overrides the shadcn
+ * HSL-triplet tokens so existing Tailwind utilities (bg-card, text-muted-
+ * foreground, bg-action-save-soft, etc.) retint correctly without any
+ * component changes.
+ *
+ * Palette: vellum cream (#fbf3dc), ink brown (#5a3a14), gold leaf
+ * (#d4a030), crimson seal (#8a1410). HSL triplets are conversions of
+ * the same hex values.
+ *
+ * Decorative layers (vellum noise, fleur-de-lis, marginalia, gilded
+ * corner ornaments) are deferred to Phase 3 fan-out — they target
+ * `.app-frame`, `.canvas`, `.sidebar` etc. which don't exist as
+ * dedicated React component classes today.
+ *
+ * Source: design_handoff_machinaos_themes/themes/renaissance.css.
+ * ============================================================================ */
+
+:root[data-theme="renaissance"] {
+ /* ── New contract — full colour values ────────────────────────────── */
+
+ /* Surfaces */
+ --bg-app: #f3e8c8;
+ --bg-panel: #ead09a;
+ --bg-canvas: #e8d4a0;
+ --bg-elevated: #fbf3dc;
+ --bg-input: #fbf3dc;
+ --bg-hover: rgba(138, 94, 28, 0.10);
+ --bg-active: rgba(212, 160, 48, 0.20);
+ --bg-overlay: rgba(58, 32, 8, 0.55);
+
+ /* Borders */
+ --border-default: #8a5e1c;
+ --border-strong: #5a3a14;
+ --border-focus: #4a8230;
+ --ornament-frame: inset 0 0 0 2px #8a5e1c, inset 0 0 0 6px #d4a030, inset 0 0 0 8px #5a3a14;
+
+ /* Foreground */
+ --fg-default: #3a2008;
+ --fg-muted: #6a4a1c;
+ --fg-faint: #8a6a3c;
+ --fg-on-accent: #fbf3dc;
+ --fg-on-success: #fbf3dc;
+ --fg-on-danger: #fbf3dc;
+ --fg-on-warning: #3a2008;
+
+ /* Theme-specific accents (used by decorative layers; safe to read in
+ * components migrated to the new contract) */
+ --gold: #d4a030;
+ --gold-bright: #f0c850;
+ --crimson: #8a1410;
+
+ /* Type — Cinzel display + Cormorant body + IM Fell English mono */
+ --font-display: 'Cinzel', 'Trajan Pro', Georgia, serif;
+ --font-body: 'Cormorant Garamond', 'EB Garamond', Georgia, serif;
+ --font-mono: 'IM Fell English', 'Courier Prime', monospace;
+ --type-scale-base: 15px;
+ --type-tracking-display: 0.10em;
+ --type-uppercase: uppercase;
+
+ /* Geometry — slim radii (parchment + wax-pressed feel) */
+ --radius-sm: 2px;
+ --radius-md: 3px;
+ --radius-lg: 4px;
+ --radius-pill: 12px;
+
+ /* Motion — slow, weighted */
+ --ease-default: cubic-bezier(0.4, 0, 0.2, 1);
+ --ease-emphasis: cubic-bezier(0.7, -0.1, 0.3, 1.2);
+ --dur-fast: 140ms;
+ --dur-default: 280ms;
+ --dur-slow: 520ms;
+ --motion-style: organic;
+ --sound-pack: parchment;
+
+ /* Cursor + scrollbar */
+ --cursor-default: auto;
+ --cursor-pointer: pointer;
+ --scrollbar-track: #e8d09a;
+ --scrollbar-thumb: #8a5e1c;
+
+ /* ── Shadcn HSL-triplet bridge ─────────────────────────────────────
+ * Same colours as the new contract above, expressed as HSL triplets
+ * so Tailwind utilities like bg-card/50 (alpha composition) keep
+ * working. */
+
+ --background: 40 65% 87%; /* #f3e8c8 */
+ --foreground: 28 76% 13%; /* #3a2008 */
+ --card: 41 79% 92%; /* #fbf3dc */
+ --card-foreground: 28 76% 13%;
+ --popover: 41 79% 92%;
+ --popover-foreground: 28 76% 13%;
+
+ --primary: 32 53% 48%; /* #b8893c gold accent */
+ --primary-foreground: 41 79% 92%;
+ --secondary: 38 65% 76%; /* #ead09a panel */
+ --secondary-foreground: 28 76% 13%;
+ --muted: 38 65% 76%;
+ --muted-foreground: 33 60% 26%; /* #6a4a1c */
+ --accent: 41 65% 51%; /* #d4a030 gold leaf */
+ --accent-foreground: 28 76% 13%;
+
+ --destructive: 2 79% 30%; /* #8a1410 crimson */
+ --destructive-foreground: 41 79% 92%;
+ --success: 78 63% 25%; /* #4a6818 olive */
+ --warning: 35 71% 44%; /* #c08020 amber */
+ --info: 211 56% 23%; /* #1a3a5a navy */
+
+ --border: 33 66% 33%; /* #8a5e1c */
+ --input: 33 66% 33%;
+ --ring: 41 65% 51%; /* gold focus */
+
+ /* Action role tokens — re-derived from Renaissance semantic palette.
+ * Keep the soft / hover / border alpha pattern so ActionButton still
+ * works without any code change. */
+ --action-run: 78 63% 25%; /* olive (success) */
+ --action-run-soft: 78 63% 25% / 0.18;
+ --action-run-hover: 78 63% 25% / 0.30;
+ --action-run-border: 78 63% 25% / 0.6;
+
+ --action-stop: 2 79% 30%; /* crimson (destructive) */
+ --action-stop-soft: 2 79% 30% / 0.15;
+ --action-stop-hover: 2 79% 30% / 0.25;
+ --action-stop-border: 2 79% 30% / 0.6;
+
+ --action-save: 41 65% 51%; /* gold leaf (primary action) */
+ --action-save-soft: 41 65% 51% / 0.20;
+ --action-save-hover: 41 65% 51% / 0.35;
+ --action-save-border: 32 53% 48% / 0.7;
+
+ --action-config: 35 71% 44%; /* amber (warning) */
+ --action-config-soft: 35 71% 44% / 0.18;
+ --action-config-hover: 35 71% 44% / 0.30;
+ --action-config-border: 35 71% 44% / 0.6;
+
+ --action-secret: 211 56% 23%; /* navy (info / secret) */
+ --action-secret-soft: 211 56% 23% / 0.15;
+ --action-secret-hover: 211 56% 23% / 0.25;
+ --action-secret-border: 211 56% 23% / 0.6;
+
+ --action-tools: 32 53% 48%; /* gold accent */
+ --action-tools-soft: 32 53% 48% / 0.18;
+ --action-tools-hover: 32 53% 48% / 0.30;
+ --action-tools-border: 32 53% 48% / 0.6;
+
+ /* Tint utilities — slightly stronger on parchment so brand-coloured
+ * surfaces (provider icons, skill colours) stay legible. */
+ --tint-soft: 14%;
+ --tint-border: 35%;
+}
+
+/* ── Body parchment background ─────────────────────────────────────────
+ * The handoff layers radial gradients + an SVG noise texture on body.
+ * Safe to apply since `body` is theme-agnostic. */
+
+:root[data-theme="renaissance"] body {
+ background:
+ radial-gradient(ellipse at 15% 25%, rgba(138, 70, 20, 0.12), transparent 35%),
+ radial-gradient(ellipse at 85% 75%, rgba(180, 100, 30, 0.10), transparent 40%),
+ radial-gradient(circle at 70% 20%, rgba(90, 50, 18, 0.08), transparent 25%),
+ url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='240' height='240'><filter id='n'><feTurbulence baseFrequency='0.85' numOctaves='3' seed='5'/><feColorMatrix values='0 0 0 0 0.36 0 0 0 0 0.23 0 0 0 0 0.05 0 0 0 0.10 0'/></filter><rect width='240' height='240' filter='url(%23n)'/></svg>"),
+ var(--bg-app);
+}
+
+/* ::selection — gold leaf highlight */
+:root[data-theme="renaissance"] ::selection {
+ background: rgba(212, 160, 48, 0.5);
+ color: #3a2008;
+}
diff --git a/docs-internal/theme_system.md b/docs-internal/theme_system.md
new file mode 100644
index 00000000..53b88709
--- /dev/null
+++ b/docs-internal/theme_system.md
@@ -0,0 +1,246 @@
+# Theme System — design-handoff token contract + 4-way themes
+
+The MachinaOs frontend supports four visual themes — **light**, **dark**, **renaissance**, **cyber** — selected at runtime via `<html data-theme="...">`. The system is purely CSS-variable-driven: components render against semantic token names, and the active `[data-theme="..."]` block in `client/src/themes/` rebinds those tokens to the theme's surface, foreground, accent, typography, geometry, and motion values.
+
+This document is the playbook for working in the design system: token taxonomy, migration recipe, anti-patterns, and where each piece lives.
+
+## Architecture at a glance
+
+```
+client/src/themes/
+├── base.css neutral defaults (space, motion easings, sound pack hint)
+├── light.css :root + :root[data-theme="light"] — new contract values
+├── dark.css .dark + :root[data-theme="dark"] — new contract values
+├── renaissance.css :root[data-theme="renaissance"] — full palette + bridge
+└── cyber.css :root[data-theme="cyber"] — full palette + bridge
+
+client/src/index.css
+├── @layer base :root — shadcn HSL-triplet tokens (light defaults)
+├── @layer base .dark — shadcn HSL-triplet tokens (dark overrides)
+└── @theme inline { … } — Tailwind v4 utility bindings for both contracts
+
+client/src/contexts/ThemeContext.tsx
+├── theme: 'light' | 'dark' | 'renaissance' | 'cyber'
+├── persists to localStorage['machinaos-theme']
+├── migrates legacy 'darkMode' boolean
+└── sets <html data-theme="..."> + (.dark class for legacy `dark:` Tailwind variants)
+
+client/src/components/ui/ThemeSwitcher.tsx — DropdownMenu in TopToolbar
+client/src/components/ui/StatusBar.tsx — fixed-bottom system console
+client/src/components/ui/CommandPalette.tsx + CommandPaletteHost.tsx — ⌘K launcher
+```
+
+## Token tiers
+
+There are five tiers, ordered from most semantic to most concrete. Always pick the most semantic that fits the call site.
+
+### 1. New-contract surface tokens (preferred for new code)
+
+Surface hierarchy across themes; every theme assigns these in its `:root[data-theme="..."]` block.
+
+| Tailwind utility | CSS var | Purpose |
+|---|---|---|
+| `bg-bg-app` | `--bg-app` | Outer page / root background |
+| `bg-bg-panel` | `--bg-panel` | Sidebars, palette, toolbar, footer chrome |
+| `bg-bg-canvas` | `--bg-canvas` | The workflow canvas |
+| `bg-bg-elevated` | `--bg-elevated` | Modals, dropdowns, popovers, cards inside panels |
+| `bg-bg-input` | `--bg-input` | Form-field backgrounds |
+| `bg-bg-hover` | `--bg-hover` | Hover state for rows / buttons |
+| `bg-bg-active` | `--bg-active` | Selected / pressed state |
+| `bg-bg-overlay` | `--bg-overlay` | Modal scrims |
+
+| Tailwind utility | CSS var | Purpose |
+|---|---|---|
+| `text-fg-default` | `--fg-default` | Primary text |
+| `text-fg-muted` | `--fg-muted` | Secondary / metadata |
+| `text-fg-faint` | `--fg-faint` | Placeholders / divider text |
+| `text-fg-on-accent` | `--fg-on-accent` | Text over `--accent` fills |
+
+| Tailwind utility | CSS var | Purpose |
+|---|---|---|
+| `border-default` | `--border-default` | Standard borders + dividers |
+| `border-strong` | `--border-strong` | Section separators, focused panels |
+| `border-focus` | `--border-focus` | Focus rings (often shadowed) |
+
+| Tailwind utility | CSS var | Purpose |
+|---|---|---|
+| `font-display` | `--font-display` | Headings, panel titles, action labels (Cinzel under Ren, Major Mono under Cyber) |
+| `font-body` | `--font-body` | Paragraph + UI copy |
+| `font-mono` | `--font-mono` | Code, console, JSON, status bar, kbd |
+
+| Tailwind utility | CSS var | Purpose |
+|---|---|---|
+| `tracking-[var(--type-tracking-display)]` | `--type-tracking-display` | Letter-spacing for display headings |
+| `[text-transform:var(--type-uppercase)]` | `--type-uppercase` | Theme-driven uppercase / capitalize / none |
+
+**Note**: full-colour values, no HSL triplet, so alpha composition (`bg-bg-app/50`) does **not** work for these. Use the shadcn alias (`bg-background/50`) when you need alpha.
+
+### 2. shadcn semantic tokens (preserved for primitives + alpha-composed call sites)
+
+Standard shadcn keys (`background`, `foreground`, `card`, `popover`, `primary`, `destructive`, `success`, `warning`, `info`, `border`, `input`, `ring`, etc.). Each theme's CSS file regenerates them as HSL triplets matching the same colour as the new-contract token, so existing utilities keep working. **Use these when you need `/50` alpha** (e.g., `bg-primary/10`, `text-foreground/80`).
+
+### 3. Action role tokens
+
+Six semantic intents: `run | stop | save | config | secret | tools`. Each exposes `base / -soft / -hover / -border` (see [client/src/index.css](../client/src/index.css)). Read via `<ActionButton intent="run">` or directly: `bg-action-run-soft text-action-run border-action-run-border`. Themes redefine these in their own block.
+
+### 4. Node-type role tokens
+
+Six tokens for canvas identity: `agent / model / skill / tool / trigger / workflow`. Each exposes `base / -soft / -border`. Used on palette icons, parameter-panel section headers, draggable variable cards. **Never use `/N` opacity arithmetic** at call sites — themes own the alpha.
+
+### 5. Dracula raw accents (palette, not consumed directly)
+
+`--dracula-green/purple/pink/cyan/red/orange/yellow/selection/current-line/comment`. Same value across light + dark. Used as the underlying palette that `--action-X` and `--node-X` reference; do not use directly in components.
+
+## Migration recipe
+
+The single most important rule from the design handoff:
+
+> Components render against `var(--token)` references only. There is no theme-conditional logic in component bodies. Every visual switch lives in the per-theme CSS file under `client/src/themes/`.
+
+Concrete swaps when migrating an existing component:
+
+| Before (legacy) | After (new contract) | When |
+|---|---|---|
+| `bg-card` (panel chrome) | `bg-bg-panel` | Sidebars, palette, toolbar, footer |
+| `bg-card` (elevated card) | `bg-bg-elevated` | Modal heads, dropdowns, settings sections, chat bubbles |
+| `bg-background` | `bg-bg-app` | Modal body, page-level backgrounds |
+| `bg-muted` (subtle distinct surface) | `bg-bg-app` or `bg-bg-elevated` | Pick by elevation intent |
+| `border-border` | `border-border-default` | Dividers, card outlines |
+| `text-foreground` | `text-fg-default` | Body text |
+| `text-muted-foreground` | `text-fg-muted` | Secondary text |
+| `text-sm font-medium` (display surface) | `font-display tracking-[var(--type-tracking-display)] [text-transform:var(--type-uppercase)] text-fg-default` | Panel titles, section headers, node labels |
+| `text-xs` (metadata / counts) | `font-mono text-xs` | Status pills, timestamps, IDs |
+| `<input>` field bg | `bg-bg-input` | Form fields |
+| Hover row | `hover:bg-bg-hover` | Lists, menu items |
+| Selected row | `bg-bg-active` | Selected workflow cards, active tabs |
+| Modal scrim | `bg-bg-overlay` | Dialog overlays |
+| `<ActionButton intent="...">` | unchanged | All toolbar / panel action buttons |
+
+### Display-typography helper
+
+Heading surfaces under all four themes use the same triplet. Keep them grouped in the same className for clarity:
+
+```tsx
+<span className="font-display tracking-[var(--type-tracking-display)] text-fg-default [text-transform:var(--type-uppercase)]">
+ {heading}
+</span>
+```
+
+Result:
+- Light/dark: clean Geist sans, no transform, no extra tracking
+- Renaissance: Cinzel uppercase, +0.10em tracking
+- Cyber: Major Mono Display uppercase, +0.18em tracking
+
+## Adding a new theme
+
+1. Drop a CSS file at `client/src/themes/<name>.css`. Required block:
+ ```css
+ :root[data-theme="<name>"] {
+ /* New contract — full colour values */
+ --bg-app: …; --bg-panel: …; --bg-canvas: …; --bg-elevated: …;
+ --bg-input: …; --bg-hover: …; --bg-active: …; --bg-overlay: …;
+ --border-default: …; --border-strong: …; --border-focus: …;
+ --fg-default: …; --fg-muted: …; --fg-faint: …;
+ --fg-on-accent: …; --fg-on-success: …; --fg-on-danger: …; --fg-on-warning: …;
+ --font-display: …; --font-body: …; --font-mono: …;
+ --type-uppercase: none|uppercase|capitalize;
+ --type-tracking-display: 0|0.10em|0.18em;
+ --radius-sm: …; --radius-md: …; --radius-lg: …; --radius-pill: …;
+
+ /* Shadcn HSL-triplet bridge — same colours, HSL form */
+ --background: H S% L%; --foreground: H S% L%;
+ --card: H S% L%; --popover: H S% L%; --primary: H S% L%;
+ --secondary: H S% L%; --muted: H S% L%; --accent: H S% L%;
+ --destructive: H S% L%; --success: H S% L%; --warning: H S% L%; --info: H S% L%;
+ --border: H S% L%; --input: H S% L%; --ring: H S% L%;
+
+ /* Action role tokens — derive from theme semantic palette */
+ --action-run: H S% L%; --action-run-soft: H S% L% / 0.18; …
+ --action-stop: H S% L%; …
+ --action-save: H S% L%; …
+ --action-config: H S% L%; …
+ --action-secret: H S% L%; …
+ --action-tools: H S% L%; …
+ }
+ ```
+2. Import it in [client/src/main.tsx](../client/src/main.tsx) **before** `index.css`.
+3. Add the name to `AVAILABLE_THEMES` in [client/src/contexts/ThemeContext.tsx](../client/src/contexts/ThemeContext.tsx).
+4. (Optional) Add a `THEME_META` entry in [client/src/components/ui/ThemeSwitcher.tsx](../client/src/components/ui/ThemeSwitcher.tsx) for the dropdown label + blurb.
+5. (Optional) If the theme uses non-system fonts, add a `<link rel="stylesheet">` in [client/index.html](../client/index.html) — currently Renaissance + Cyber load Cinzel / Cormorant Garamond / IM Fell English / Major Mono Display / VT323 / JetBrains Mono via the deferred Google Fonts link there.
+
+**No component code changes.** That is the contract.
+
+## Anti-patterns (forbidden)
+
+1. **Theme-conditional logic in components.** No `if (theme === 'cyber')` branches. Visual differences live in the per-theme CSS file.
+2. **Whole-store Zustand destructure.** Always `useAppStore((s) => s.x)`, never `{ x } = useAppStore()`.
+3. **Opacity arithmetic on new-contract tokens.** `bg-bg-app/10` does not work — they're full-colour. Add a new variant under `client/src/themes/<name>.css` if you need a different alpha, or fall back to the shadcn alias (`bg-background/10`).
+4. **Hardcoded colours.** No `bg-white`, `bg-black`, `text-gray-500`, `style={{ backgroundColor: '#fff' }}`. Use tokens.
+5. **`useAppTheme()` in new files.** Grandfathered for canvas node components (`AIAgentNode`, `SquareNode`, `TriggerNode`, `StartNode`, `ToolkitNode`, `TeamMonitorNode`, `GenericNode`) and `EdgeConditionEditor` — they interpolate per-definition `nodeColor` into gradients. Plus `MapSelector` / `GoogleMapsPicker` which need hex for the Maps SDK. Every other surface uses Tailwind + tokens.
+6. **Hand-rolled modal backdrops.** Use `<Modal>` from `client/src/components/ui/Modal.tsx`.
+7. **Hand-rolled colored buttons.** Use `<ActionButton intent="...">`.
+8. **Static fallback theme palettes in TS.** Themes live in CSS, not TS exports. The `client/src/styles/theme.ts` file is grandfathered for the canvas + Maps SDK only.
+
+## What's done vs deferred
+
+### Done (this migration)
+- Token contract: 4 themes (light, dark, renaissance, cyber)
+- ThemeProvider extended; legacy `darkMode` localStorage migration
+- ThemeSwitcher in TopToolbar
+- Tailwind v4 `@theme inline` exposing new utilities
+- Migrated: Modal, TopToolbar, WorkflowSidebar, ComponentPalette, ComponentItem, CollapsibleSection, ConsolePanel chrome, SettingsPanel
+- New: StatusBar (fixed-bottom system console), CommandPalette (⌘K), CommandPaletteHost
+- Google Fonts deferred-load
+- Build + typecheck clean
+
+### Deferred (future PRs)
+- **Canvas nodes**: `AIAgentNode`, `SquareNode`, `TriggerNode`, `StartNode`, `ToolkitNode`, `TeamMonitorNode`, `GenericNode` still call `useAppTheme()` for inline gradients tied to per-node colours. Under Renaissance/Cyber they'll use the light or dark palette (depending on `isDarkMode`). To fully migrate, extend `useAppTheme` to return one of four colour packs, or move per-node gradient styles into per-theme CSS.
+- **Parameter panel internals** (`ParameterRenderer`, `MiddleSection`, `MasterSkillEditor`): consume shadcn semantic tokens through the bridge — function correctly under all themes but headers don't yet pick up `font-display`. Apply the migration recipe above when touching them.
+- **Credentials modal sub-panels** (`OAuthPanel`, `EmailPanel`, `ApiKeyPanel`, `QrPairingPanel`): same — inherit via the bridge, can be promoted when touched.
+- **Decorative layers** from the design handoff (vellum noise, fleur-de-lis, scanlines, CRT flicker on `.app-frame`): per-theme CSS files include the body-level background gradients, but per-component decorations (corner ornaments, marginalia, scanlines on modals) target classes like `.app-frame`, `.canvas`, `.sq-node` that don't always exist in the React tree. Add wrapper classes (e.g., add `app-frame` to the Dashboard root) and import the decorative blocks from `design_handoff_machinaos_themes/themes/` as the surfaces stabilise.
+- **Sound pack** (`--sound-pack` token): each theme declares its sound name (`parchment`, `terminal`, `chime`); JS hook + WebAudio implementation are tracked on the handoff but not yet wired.
+
+## Verification checklist
+
+When changing a component, verify under all four themes:
+
+```bash
+cd client && pnpm dev
+```
+
+1. `<html data-theme="light">` — clean default, near-white surfaces
+2. `<html data-theme="dark">` — Solarized + Dracula
+3. `<html data-theme="renaissance">` — parchment, gold accents, Cinzel headings
+4. `<html data-theme="cyber">` — neon over void, JetBrains Mono everywhere
+
+Build + typecheck must stay clean:
+
+```bash
+cd client && pnpm typecheck && pnpm build
+```
+
+Touched components should pass lint:
+
+```bash
+cd client && npx eslint <files>
+```
+
+## File index
+
+| File | Role |
+|---|---|
+| [client/src/themes/base.css](../client/src/themes/base.css) | Neutral defaults |
+| [client/src/themes/light.css](../client/src/themes/light.css) | Light theme tokens |
+| [client/src/themes/dark.css](../client/src/themes/dark.css) | Dark theme tokens |
+| [client/src/themes/renaissance.css](../client/src/themes/renaissance.css) | Renaissance theme + bridge |
+| [client/src/themes/cyber.css](../client/src/themes/cyber.css) | Cyber theme + bridge |
+| [client/src/index.css](../client/src/index.css) | shadcn HSL triplets + `@theme inline` Tailwind utilities |
+| [client/src/contexts/ThemeContext.tsx](../client/src/contexts/ThemeContext.tsx) | `<ThemeProvider>` + `useTheme()` |
+| [client/src/components/ui/ThemeSwitcher.tsx](../client/src/components/ui/ThemeSwitcher.tsx) | Dropdown picker in TopToolbar |
+| [client/src/components/ui/StatusBar.tsx](../client/src/components/ui/StatusBar.tsx) | Fixed-bottom system line |
+| [client/src/components/ui/CommandPalette.tsx](../client/src/components/ui/CommandPalette.tsx) | ⌘K palette primitive |
+| [client/src/components/ui/CommandPaletteHost.tsx](../client/src/components/ui/CommandPaletteHost.tsx) | Registered command set |
+| [client/src/components/ui/action-button.tsx](../client/src/components/ui/action-button.tsx) | CVA action role primitive |
+| [client/src/components/ui/Modal.tsx](../client/src/components/ui/Modal.tsx) | Shared modal layout |
+| [client/index.html](../client/index.html) | Google Fonts loading |
+| [design_handoff_machinaos_themes/](../design_handoff_machinaos_themes/) | Reference HTML mocks + token spec |