Skip to content

Self-improving AI Employees for everyone

feat(theme): full 10-theme design system + decorative + sound + canvas overlays (Wave 14)

trohitg5ff617f1a82b
diff --git a/CLAUDE.md b/CLAUDE.md
index e19e79fe..eea82942 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -11,7 +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. |
+| **[Theme System](./docs-internal/theme_system.md)** | 10-way visual theme system — 5 utopian (light, dark, renaissance, greek, edo, steampunk, atomic) + 5 dystopian (cyber, wasteland, rot, plague, surveillance) — driven by `<html data-theme>` + per-theme CSS files in `client/src/themes/`. Token taxonomy (surface / fg / border / accent / typography / motion), shadcn HSL-triplet bridge, action role tokens, decorative-layer wrappers (`.app-frame` / `.canvas-host` / `.modal-frame`), per-theme WebAudio sound packs (10 packs via `--sound-pack` token + `useSound()` hook), migration recipe, anti-patterns. 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 f9752ebe..173b32ff 100644
--- a/client/index.html
+++ b/client/index.html
@@ -21,14 +21,14 @@
<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"
+ href="https://fonts.googleapis.com/css2?family=Anonymous+Pro:ital,wght@0,400;0,700;1,400&family=Bevan&family=Cinzel:wght@400;600;700&family=Cormorant+Garamond:ital,wght@0,400;0,500;0,600;1,400&family=Courier+Prime:ital,wght@0,400;0,700;1,400&family=EB+Garamond:ital,wght@0,400;0,500;0,600;1,400&family=IBM+Plex+Mono:ital,wght@0,400;0,500;0,600;1,400&family=IM+Fell+English+SC&family=IM+Fell+English:ital@0;1&family=JetBrains+Mono:wght@400;500;600;700&family=Lato:wght@400;700&family=Major+Mono+Display&family=Pirata+One&family=Sawarabi+Mincho&family=Shippori+Mincho:wght@400;500;600;700&family=Space+Mono:ital,wght@0,400;0,700;1,400&family=Special+Elite&family=UnifrakturCook:wght@700&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"
+ href="https://fonts.googleapis.com/css2?family=Anonymous+Pro:ital,wght@0,400;0,700;1,400&family=Bevan&family=Cinzel:wght@400;600;700&family=Cormorant+Garamond:ital,wght@0,400;0,500;0,600;1,400&family=Courier+Prime:ital,wght@0,400;0,700;1,400&family=EB+Garamond:ital,wght@0,400;0,500;0,600;1,400&family=IBM+Plex+Mono:ital,wght@0,400;0,500;0,600;1,400&family=IM+Fell+English+SC&family=IM+Fell+English:ital@0;1&family=JetBrains+Mono:wght@400;500;600;700&family=Lato:wght@400;700&family=Major+Mono+Display&family=Pirata+One&family=Sawarabi+Mincho&family=Shippori+Mincho:wght@400;500;600;700&family=Space+Mono:ital,wght@0,400;0,700;1,400&family=Special+Elite&family=UnifrakturCook:wght@700&family=VT323&display=swap"
/>
</noscript>
<title>MachinaOS</title>
diff --git a/client/src/Dashboard.tsx b/client/src/Dashboard.tsx
index e1186138..dac0ddee 100644
--- a/client/src/Dashboard.tsx
+++ b/client/src/Dashboard.tsx
@@ -37,6 +37,7 @@ 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 { useSoundSync } from './hooks/useSound';
import { useAppTheme } from './hooks/useAppTheme';
import { useWorkflowManagement } from './hooks/useWorkflowManagement';
import { useWorkflowsQuery, WORKFLOWS_QUERY_KEY } from './hooks/useWorkflowsQuery';
@@ -285,6 +286,12 @@ const DashboardContent: React.FC = () => {
const consolePanelVisible = useAppStore((state) => state.consolePanelVisible);
const toggleConsolePanelVisible = useAppStore((state) => state.toggleConsolePanelVisible);
+ // Sound effects: mirror the soundEnabled slice into the WebAudio
+ // engine and re-read --sound-pack from :root on every theme change.
+ // Mounting once here keeps every event handler that calls useSound()
+ // in lockstep with the active theme + user preference.
+ useSoundSync();
+
// Context menu state for node right-click
const [contextMenu, setContextMenu] = React.useState<{
nodeId: string;
@@ -1097,7 +1104,13 @@ const DashboardContent: React.FC = () => {
return (
<>
<style>{buildCanvasStyles(theme.colors)}</style>
- <div style={{
+ {/* `app-frame` is the decorative-layer hook from the design handoff —
+ per-theme CSS files target this class for outer ornaments
+ (gilded corners under Renaissance, scanline overlay + corner
+ brackets under Cyber, riveted ridged frame under Steampunk,
+ REC dot under Surveillance, etc.). Decorations declare
+ pointer-events: none so they don't intercept clicks. */}
+ <div className="app-frame" style={{
width: '100%',
height: '100vh',
display: 'flex',
@@ -1165,10 +1178,18 @@ const DashboardContent: React.FC = () => {
display: 'flex',
position: 'relative',
}}>
- <div style={{
- flex: 1,
- backgroundColor: theme.colors.backgroundAlt,
- }}>
+ {/* `canvas-host` activates per-theme canvas decorations
+ (cyber grid backplane, atomic starburst, rot candlelight
+ pools, surveillance crosshair brackets). Decorative
+ pseudo-elements declare pointer-events: none. */}
+ <div
+ className="canvas-host"
+ style={{
+ flex: 1,
+ backgroundColor: theme.colors.backgroundAlt,
+ position: 'relative',
+ }}
+ >
<ErrorBoundary>
<ReactFlow
nodes={styledNodes}
diff --git a/client/src/ParameterPanel.tsx b/client/src/ParameterPanel.tsx
index 3d67deaf..db63f14b 100644
--- a/client/src/ParameterPanel.tsx
+++ b/client/src/ParameterPanel.tsx
@@ -136,7 +136,7 @@ const ParameterPanel: React.FC = () => {
// Header actions with node name and buttons in middle area
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)]">
<NodeIcon
icon={nodeDefinition.icon}
className="h-5 w-5 text-xl"
diff --git a/client/src/components/parameterPanel/InputSection.tsx b/client/src/components/parameterPanel/InputSection.tsx
index 948f8a71..b9362a64 100644
--- a/client/src/components/parameterPanel/InputSection.tsx
+++ b/client/src/components/parameterPanel/InputSection.tsx
@@ -518,7 +518,7 @@ const InputSection: React.FC<InputSectionProps> = ({ nodeId, visible = true }) =
{/* Header */}
<div className="flex shrink-0 items-center gap-2 border-b border-border bg-background px-4 py-3">
<Database className="h-4 w-4 text-muted-foreground" />
- <span className="text-sm font-semibold text-foreground">Input Data &amp; Variables</span>
+ <span className="font-display text-sm font-semibold tracking-[var(--type-tracking-display)] text-fg-default [text-transform:var(--type-uppercase)]">Input Data &amp; Variables</span>
<Badge variant="info">{connectedNodes.length}</Badge>
</div>
@@ -541,7 +541,7 @@ const InputSection: React.FC<InputSectionProps> = ({ nodeId, visible = true }) =
>
<div className="flex items-center gap-2">
<NodeIcon icon={node.icon} className="h-5 w-5 text-lg" />
- <span className="text-sm font-semibold text-foreground">{node.name}</span>
+ <span className="font-display text-sm font-semibold text-fg-default">{node.name}</span>
</div>
<div className="flex items-center gap-2">
<Badge variant={node.hasExecutionData ? 'success' : 'warning'}>
diff --git a/client/src/components/ui/AIResultModal.tsx b/client/src/components/ui/AIResultModal.tsx
index e319cd7f..dd8b2317 100644
--- a/client/src/components/ui/AIResultModal.tsx
+++ b/client/src/components/ui/AIResultModal.tsx
@@ -51,7 +51,7 @@ const AIResultModal: React.FC<AIResultModalProps> = ({ isOpen, onClose, result }
<div className="border-b border-border bg-muted p-4">
<div className="mb-2 flex items-start justify-between">
<div>
- <h3 className="m-0 text-base font-semibold text-foreground">
+ <h3 className="m-0 font-display text-base font-semibold tracking-[var(--type-tracking-display)] text-fg-default [text-transform:var(--type-uppercase)]">
{result.nodeName} Result
</h3>
<p className="mt-1 mb-0 text-sm text-muted-foreground">
diff --git a/client/src/components/ui/CommandPaletteHost.tsx b/client/src/components/ui/CommandPaletteHost.tsx
index d6505b53..a786bc46 100644
--- a/client/src/components/ui/CommandPaletteHost.tsx
+++ b/client/src/components/ui/CommandPaletteHost.tsx
@@ -48,10 +48,18 @@ interface Handlers {
}
const THEME_LABEL: Record<ThemeName, string> = {
- light: 'Light',
- dark: 'Dark',
- renaissance: 'Renaissance',
- cyber: 'Cyber-Tyranny',
+ light: 'Light',
+ dark: 'Dark',
+ renaissance: 'Renaissance',
+ greek: 'Greek',
+ edo: 'Edo',
+ steampunk: 'Steampunk',
+ atomic: 'Atomic Modern',
+ cyber: 'Cyber-Tyranny',
+ wasteland: 'Wasteland',
+ rot: 'Necromantic Rot',
+ plague: 'Plague City',
+ surveillance: 'Surveillance',
};
interface Props {
diff --git a/client/src/components/ui/Modal.tsx b/client/src/components/ui/Modal.tsx
index e188bbcf..0b402b25 100644
--- a/client/src/components/ui/Modal.tsx
+++ b/client/src/components/ui/Modal.tsx
@@ -9,7 +9,7 @@
* if you need a new prop.
*/
-import React from 'react';
+import React, { useEffect, useRef } from 'react';
import { X, Settings } from 'lucide-react';
import {
Dialog,
@@ -21,6 +21,7 @@ import {
} from '@/components/ui/dialog';
import { Dialog as DialogPrimitive } from 'radix-ui';
import { cn } from '@/lib/utils';
+import { Sounds } from '@/lib/sound';
interface ModalProps {
isOpen: boolean;
@@ -62,6 +63,18 @@ const Modal: React.FC<ModalProps> = ({
}) => {
const showHeader = Boolean(title || headerActions);
+ // Fire per-theme open/close sounds on isOpen transitions only — not
+ // on first mount (use a previous-value ref to detect the actual
+ // edge). Sounds.play is a no-op when the engine is disabled.
+ const prevOpenRef = useRef(isOpen);
+ useEffect(() => {
+ const prev = prevOpenRef.current;
+ if (prev !== isOpen) {
+ Sounds.play(isOpen ? 'modalOpen' : 'modalClose');
+ prevOpenRef.current = isOpen;
+ }
+ }, [isOpen]);
+
return (
<Dialog open={isOpen} onOpenChange={(next) => { if (!next) onClose(); }}>
<DialogPortal>
@@ -76,6 +89,12 @@ const Modal: React.FC<ModalProps> = ({
// tokens directly so modals inherit the surface hierarchy
// defined by the active theme (parchment under Renaissance,
// void under Cyber).
+ //
+ // `modal-frame` is the decorative-layer hook — per-theme
+ // CSS targets this class for nailed-up borders (Plague),
+ // gilded corners (Renaissance), neon scanlines (Cyber),
+ // double-rule frames (Greek), etc.
+ 'modal-frame',
'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
diff --git a/client/src/components/ui/OutputDisplayPanel.tsx b/client/src/components/ui/OutputDisplayPanel.tsx
index 2432a994..703051da 100644
--- a/client/src/components/ui/OutputDisplayPanel.tsx
+++ b/client/src/components/ui/OutputDisplayPanel.tsx
@@ -156,7 +156,7 @@ const OutputDisplayPanel: React.FC<OutputDisplayPanelProps> = ({ results, onClea
<div className="flex items-center justify-between border-b border-border bg-background px-4 py-3">
<div className="flex items-center gap-2">
<Play className="h-4 w-4 text-success" />
- <span className="text-sm font-semibold text-foreground">Execution Results</span>
+ <span className="font-display text-sm font-semibold tracking-[var(--type-tracking-display)] text-fg-default [text-transform:var(--type-uppercase)]">Execution Results</span>
<Badge variant="secondary" className="text-xs">{results.length}</Badge>
</div>
{onClear && (
diff --git a/client/src/components/ui/SettingsPanel.tsx b/client/src/components/ui/SettingsPanel.tsx
index b342a37e..17cfccb0 100644
--- a/client/src/components/ui/SettingsPanel.tsx
+++ b/client/src/components/ui/SettingsPanel.tsx
@@ -9,7 +9,9 @@ import {
HelpCircle,
RotateCcw,
X,
+ Volume2,
} from 'lucide-react';
+import { useAppStore } from '../../store/useAppStore';
import { Button } from '@/components/ui/button';
import { ActionButton } from '@/components/ui/action-button';
@@ -44,12 +46,13 @@ interface SettingsPanelProps {
// Reusable row + section primitives
// ---------------------------------------------------------------------------
-type SectionTone = 'agent' | 'model' | 'workflow';
+type SectionTone = 'agent' | 'model' | 'workflow' | 'tool';
const TONE_CLASSES: Record<SectionTone, string> = {
agent: 'bg-node-agent-soft text-node-agent',
model: 'bg-node-model-soft text-node-model',
workflow: 'bg-node-workflow-soft text-node-workflow',
+ tool: 'bg-node-tool-soft text-node-tool',
};
interface SectionProps {
@@ -108,6 +111,12 @@ const SettingsPanel: React.FC<SettingsPanelProps> = ({
const isLoading = settingsQuery.isLoading;
const isSaving = saveMutation.isPending;
+ // Sound preference lives in the global UI store (not the per-user
+ // server settings row) because it's gated by browser autoplay policy
+ // and persists locally only.
+ const soundEnabled = useAppStore((s) => s.soundEnabled);
+ const setSoundEnabled = useAppStore((s) => s.setSoundEnabled);
+
// Hydrate Dashboard's controlled state from the cached settings row
// exactly once per open. The query is shared with useOnboarding so
// cross-component reads stay in sync.
@@ -350,6 +359,21 @@ const SettingsPanel: React.FC<SettingsPanelProps> = ({
</Row>
</Section>
+ {/* Audio — per-theme WebAudio sound packs. Off by default;
+ honours browser autoplay policy (engine resumes on first
+ user gesture). */}
+ <Section title="Audio" Icon={Volume2} tone="tool">
+ <Row
+ label="Sound Effects"
+ description="Play per-theme click / hover / save / error sounds. Each theme ships a different pack (parchment, terminal, marble, ink, clockwork, ...). Disabled by default."
+ >
+ <Switch
+ checked={soundEnabled}
+ onCheckedChange={setSoundEnabled}
+ />
+ </Row>
+ </Section>
+
{/* Help */}
<Section title="Help" Icon={HelpCircle} tone="model">
<Row
diff --git a/client/src/components/ui/StatusBar.tsx b/client/src/components/ui/StatusBar.tsx
index fed21752..8233645b 100644
--- a/client/src/components/ui/StatusBar.tsx
+++ b/client/src/components/ui/StatusBar.tsx
@@ -18,10 +18,18 @@ 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',
+ light: 'LIGHT',
+ dark: 'DARK',
+ renaissance: 'RENAISSANCE',
+ greek: 'GREEK',
+ edo: 'EDO',
+ steampunk: 'STEAMPUNK',
+ atomic: 'ATOMIC',
+ cyber: 'CYBER',
+ wasteland: 'WASTELAND',
+ rot: 'ROT',
+ plague: 'PLAGUE',
+ surveillance: 'SURVEILLANCE',
};
interface StatusBarProps {
diff --git a/client/src/components/ui/ThemeSwitcher.tsx b/client/src/components/ui/ThemeSwitcher.tsx
index a495d7a3..6c3a949b 100644
--- a/client/src/components/ui/ThemeSwitcher.tsx
+++ b/client/src/components/ui/ThemeSwitcher.tsx
@@ -1,12 +1,14 @@
/**
* ThemeSwitcher — picks the active visual theme.
*
- * Renders one DropdownMenu item per theme listed in `AVAILABLE_THEMES`.
- * Selection persists via ThemeContext (localStorage `machinaos-theme`).
+ * Renders one DropdownMenu item per theme listed in `AVAILABLE_THEMES`,
+ * grouped into System / Utopian / Dystopian sections per the design
+ * handoff's dual taxonomy.
*
* 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.
+ * it in main.tsx, add the name to `AVAILABLE_THEMES` in ThemeContext,
+ * and add an entry to `THEME_META` + the matching `THEME_GROUPS` row
+ * below.
*/
import * as React from 'react';
@@ -28,14 +30,35 @@ interface ThemeMeta {
}
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' },
+ light: { label: 'Light', blurb: 'Clean default' },
+ dark: { label: 'Dark', blurb: 'Solarized + Dracula' },
+ renaissance: { label: 'Renaissance', blurb: 'Illuminated codex' },
+ greek: { label: 'Greek', blurb: 'Sun-bleached marble agora' },
+ edo: { label: 'Edo', blurb: 'Washi paper, sumi ink' },
+ steampunk: { label: 'Steampunk', blurb: 'Riveted brass + leather' },
+ atomic: { label: 'Atomic Modern', blurb: 'Eames mid-century' },
+ cyber: { label: 'Cyber-Tyranny', blurb: 'Neon night market' },
+ wasteland: { label: 'Wasteland', blurb: 'Irradiated scrap + rust' },
+ rot: { label: 'Necromantic Rot',blurb: 'Moss-overgrown crypt' },
+ plague: { label: 'Plague City', blurb: 'Quarantine notices' },
+ surveillance: { label: 'Surveillance', blurb: 'Institutional CCTV' },
};
+interface ThemeGroup {
+ heading: string;
+ themes: readonly ThemeName[];
+}
+
+/** Order of sections + members within each section. Drives the
+ * dropdown layout; AVAILABLE_THEMES flat list is unchanged. */
+const THEME_GROUPS: readonly ThemeGroup[] = [
+ { heading: 'System', themes: ['light', 'dark'] },
+ { heading: 'Utopian', themes: ['renaissance', 'greek', 'edo', 'steampunk', 'atomic'] },
+ { heading: 'Dystopian', themes: ['cyber', 'wasteland', 'rot', 'plague', 'surveillance'] },
+];
+
export const ThemeSwitcher: React.FC<{ className?: string }> = ({ className }) => {
- const { theme, setTheme, availableThemes } = useTheme();
+ const { theme, setTheme } = useTheme();
const activeMeta = THEME_META[theme];
return (
@@ -50,30 +73,34 @@ export const ThemeSwitcher: React.FC<{ className?: string }> = ({ className }) =
<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 align="end" className={className ?? 'min-w-[240px]'}>
+ {THEME_GROUPS.map((group, groupIdx) => (
+ <React.Fragment key={group.heading}>
+ {groupIdx > 0 && <DropdownMenuSeparator />}
+ <DropdownMenuLabel className="text-xs uppercase tracking-wider text-muted-foreground">
+ {group.heading}
+ </DropdownMenuLabel>
+ {group.themes.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>
+ );
+ })}
+ </React.Fragment>
+ ))}
</DropdownMenuContent>
</DropdownMenu>
);
diff --git a/client/src/components/ui/action-button.tsx b/client/src/components/ui/action-button.tsx
index 2d94fb5a..fc1e5c5f 100644
--- a/client/src/components/ui/action-button.tsx
+++ b/client/src/components/ui/action-button.tsx
@@ -17,6 +17,7 @@
import * as React from 'react';
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';
+import { Sounds } from '@/lib/sound';
export const actionButtonVariants = cva(
// Base: 32px tall pill with icon-text gap, semibold, focus ring, smooth hover.
@@ -51,13 +52,31 @@ export interface ActionButtonProps
VariantProps<typeof actionButtonVariants> {}
export const ActionButton = React.forwardRef<HTMLButtonElement, ActionButtonProps>(
- ({ className, intent, ...props }, ref) => (
- <button
- ref={ref}
- type={props.type ?? 'button'}
- className={cn(actionButtonVariants({ intent }), className)}
- {...props}
- />
- ),
+ ({ className, intent, onClick, ...props }, ref) => {
+ // Fire the per-theme `click` sound BEFORE the user-supplied
+ // handler so the audio cue doesn't depend on the action
+ // succeeding (e.g., even a disabled-late workflow run still
+ // gives feedback). Sounds.play() is a no-op when the engine is
+ // disabled or the active pack is `none`, so this costs nothing
+ // in the default state.
+ const handleClick = onClick
+ ? (event: React.MouseEvent<HTMLButtonElement>) => {
+ Sounds.play('click');
+ onClick(event);
+ }
+ : (_event: React.MouseEvent<HTMLButtonElement>) => {
+ Sounds.play('click');
+ };
+
+ return (
+ <button
+ ref={ref}
+ type={props.type ?? 'button'}
+ className={cn(actionButtonVariants({ intent }), className)}
+ onClick={handleClick}
+ {...props}
+ />
+ );
+ },
);
ActionButton.displayName = 'ActionButton';
diff --git a/client/src/contexts/ThemeContext.tsx b/client/src/contexts/ThemeContext.tsx
index fd681b14..31781825 100644
--- a/client/src/contexts/ThemeContext.tsx
+++ b/client/src/contexts/ThemeContext.tsx
@@ -15,15 +15,27 @@
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'];
+export type ThemeName =
+ | 'light' | 'dark'
+ | 'renaissance' | 'greek' | 'edo' | 'steampunk' | 'atomic'
+ | 'cyber' | 'wasteland' | 'rot' | 'plague' | 'surveillance';
+
+/** Order matters — drives the ThemeSwitcher menu and keyboard rotation.
+ * Utopian set first (light + dark + 5 utopian), dystopian set after. */
+export const AVAILABLE_THEMES: readonly ThemeName[] = [
+ 'light', 'dark',
+ 'renaissance', 'greek', 'edo', 'steampunk', 'atomic',
+ 'cyber', 'wasteland', 'rot', 'plague', 'surveillance',
+];
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']);
+/** Themes whose backgrounds are dark — also flip the legacy `.dark`
+ * Tailwind variant so existing `dark:` utilities resolve correctly. */
+const DARK_FAMILY: ReadonlySet<ThemeName> = new Set([
+ 'dark', 'cyber', 'wasteland', 'rot', 'surveillance', 'steampunk',
+]);
interface ThemeContextType {
theme: ThemeName;
diff --git a/client/src/hooks/useAppTheme.ts b/client/src/hooks/useAppTheme.ts
index c3a354ec..1eee789e 100644
--- a/client/src/hooks/useAppTheme.ts
+++ b/client/src/hooks/useAppTheme.ts
@@ -1,17 +1,219 @@
+/**
+ * useAppTheme — canvas + map theme accessor.
+ *
+ * Returns a flat colour pack with the same shape the canvas + map +
+ * grandfathered-modal call sites expect (`theme.colors.X`,
+ * `theme.isDarkMode`). Under light/dark this is identity-pass; under
+ * Renaissance / Greek / Edo / Steampunk / Atomic / Cyber / Wasteland
+ * / Rot / Plague / Surveillance the base pack (light or dark, picked
+ * by `DARK_FAMILY`) gets a small overlay of theme-specific accents
+ * (primary, edges, action colours) so canvas selection rings, edge
+ * strokes, and action button colours match the theme's identity.
+ *
+ * This is the production realisation of MIGRATION_PLAYBOOK Wave 1 —
+ * the upstream playbook proposes a full per-theme NodePack record;
+ * the overlay form here is the same idea expressed without forking
+ * the existing 50-key Colors shape, so the existing 14+ call sites
+ * keep compiling and the visual delta lives in one place.
+ *
+ * Adding a new theme override: drop an entry in `THEME_OVERRIDES`
+ * with whichever subset of `Colors` keys you want to override. Empty
+ * overrides are a no-op (theme falls back to pure light/dark).
+ */
+
import { useMemo } from 'react';
-import { useTheme } from '../contexts/ThemeContext';
+import { useTheme, type ThemeName } from '../contexts/ThemeContext';
import { theme as baseTheme, lightColors, darkColors } from '../styles/theme';
+type Colors = typeof lightColors;
+/** Loose form for override entries — `lightColors` is `as const`, which
+ * narrows each value to a literal hex string. Themes need to substitute
+ * arbitrary hex / rgba strings, so the override map widens to `string`. */
+type ColorOverride = Partial<Record<keyof Colors, string>>;
+
+/** Themes whose canvas + chrome read as dark backgrounds. Mirrors the
+ * DARK_FAMILY in ThemeContext so the two stay in lockstep. */
+const DARK_BASE_THEMES: ReadonlySet<ThemeName> = new Set([
+ 'dark', 'cyber', 'wasteland', 'rot', 'surveillance', 'steampunk',
+]);
+
+/** Theme-specific overlays. Each entry is a partial Colors object —
+ * whatever keys appear here override the chosen base pack. Missing
+ * keys fall through to lightColors / darkColors. Hex values come
+ * from the matching client/src/themes/<theme>.css token block. */
+const THEME_OVERRIDES: Partial<Record<ThemeName, ColorOverride>> = {
+ renaissance: {
+ primary: '#b8893c', // gold accent
+ focus: '#d4a030',
+ focusRing: 'rgba(212, 160, 48, 0.35)',
+ actionRun: '#4a6818', // olive (success)
+ actionDeploy: '#b8893c', // gold
+ actionStop: '#8a1410', // crimson
+ actionSave: '#d4a030', // gold leaf
+ edgeDefault: '#5a3a14', // ink brown
+ edgeSelected: '#d4a030', // gold
+ edgeCompleted: '#4a6818',
+ edgeError: '#8a1410',
+ edgeMemoryActive: '#b8893c',
+ edgeToolActive: '#c08020',
+ },
+
+ greek: {
+ primary: '#284b82', // lapis
+ focus: '#284b82',
+ focusRing: 'rgba(40, 75, 130, 0.3)',
+ actionRun: '#6a7a32', // olive
+ actionDeploy: '#284b82', // lapis
+ actionStop: '#7a1a18', // oxblood
+ actionSave: '#c8a040', // gold
+ edgeDefault: '#4a3818', // dark stone
+ edgeSelected: '#284b82',
+ edgeCompleted: '#6a7a32',
+ edgeError: '#7a1a18',
+ edgeMemoryActive: '#284b82',
+ edgeToolActive: '#c8a040',
+ },
+
+ edo: {
+ primary: '#b41e1e', // vermillion
+ focus: '#b41e1e',
+ focusRing: 'rgba(180, 30, 30, 0.3)',
+ actionRun: '#4a6a3a', // bamboo
+ actionDeploy: '#b41e1e',
+ actionStop: '#b41e1e',
+ actionSave: '#1a1410', // sumi
+ edgeDefault: '#1a1410',
+ edgeSelected: '#b41e1e',
+ edgeCompleted: '#4a6a3a',
+ edgeError: '#b41e1e',
+ edgeMemoryActive: '#b41e1e',
+ edgeToolActive: '#c89832',
+ },
+
+ steampunk: {
+ primary: '#d8a848', // brass
+ focus: '#d8a848',
+ focusRing: 'rgba(216, 168, 72, 0.4)',
+ actionRun: '#6a8a3a',
+ actionDeploy: '#d8a848',
+ actionStop: '#8a3a1a', // rust
+ actionSave: '#b8602a', // copper
+ edgeDefault: '#b88838',
+ edgeSelected: '#d8a848',
+ edgeCompleted: '#6a8a3a',
+ edgeError: '#8a3a1a',
+ edgeMemoryActive: '#b8602a',
+ edgeToolActive: '#d8a848',
+ },
+
+ atomic: {
+ primary: '#e85a26', // atomic orange
+ focus: '#e85a26',
+ focusRing: 'rgba(232, 90, 38, 0.4)',
+ actionRun: '#5a8a5a',
+ actionDeploy: '#e85a26',
+ actionStop: '#e85a26',
+ actionSave: '#3a9aa0', // turquoise
+ edgeDefault: '#2a3a4a', // slate
+ edgeSelected: '#e85a26',
+ edgeCompleted: '#5a8a5a',
+ edgeError: '#e85a26',
+ edgeMemoryActive: '#3a9aa0',
+ edgeToolActive: '#d8a838', // mustard
+ },
+
+ cyber: {
+ primary: '#f51eb6', // neon magenta
+ focus: '#1dd9e5', // neon cyan
+ focusRing: 'rgba(245, 30, 182, 0.5)',
+ actionRun: '#26d97a', // neon green
+ actionDeploy: '#f51eb6',
+ actionStop: '#ff2050',
+ actionSave: '#1dd9e5',
+ edgeDefault: '#f51eb6',
+ edgeSelected: '#1dd9e5',
+ edgeCompleted: '#26d97a',
+ edgeError: '#ff2050',
+ edgeMemoryActive: '#f51eb6',
+ edgeToolActive: '#ffd028', // neon yellow
+ },
+
+ wasteland: {
+ primary: '#e88a28', // ochre
+ focus: '#e88a28',
+ focusRing: 'rgba(232, 138, 40, 0.45)',
+ actionRun: '#8a9028',
+ actionDeploy: '#e88a28',
+ actionStop: '#b8281a', // rust red
+ actionSave: '#c8d038', // radioactive
+ edgeDefault: '#8a3a18',
+ edgeSelected: '#e88a28',
+ edgeCompleted: '#8a9028',
+ edgeError: '#b8281a',
+ edgeMemoryActive: '#e88a28',
+ edgeToolActive: '#c8d038',
+ },
+
+ rot: {
+ primary: '#78c878', // moss bloom
+ focus: '#78c878',
+ focusRing: 'rgba(120, 200, 120, 0.4)',
+ actionRun: '#78c878',
+ actionDeploy: '#e8a838', // candleflame
+ actionStop: '#a83838',
+ actionSave: '#e8a838',
+ edgeDefault: '#4a6a4a',
+ edgeSelected: '#78c878',
+ edgeCompleted: '#78c878',
+ edgeError: '#a83838',
+ edgeMemoryActive: '#e8a838',
+ edgeToolActive: '#5898b8',
+ },
+
+ plague: {
+ primary: '#783c28', // dried blood
+ focus: '#783c28',
+ focusRing: 'rgba(120, 60, 40, 0.4)',
+ actionRun: '#5a7028',
+ actionDeploy: '#783c28',
+ actionStop: '#783c28',
+ actionSave: '#98a838', // bile
+ edgeDefault: '#2a1c14',
+ edgeSelected: '#783c28',
+ edgeCompleted: '#5a7028',
+ edgeError: '#783c28',
+ edgeMemoryActive: '#98a838',
+ edgeToolActive: '#4a5868',
+ },
+
+ surveillance: {
+ primary: '#e82626', // REC red
+ focus: '#e82626',
+ focusRing: 'rgba(232, 38, 38, 0.45)',
+ actionRun: '#6acc6a', // phosphor green
+ actionDeploy: '#e82626',
+ actionStop: '#e82626',
+ actionSave: '#6acc6a',
+ edgeDefault: '#5a5e62',
+ edgeSelected: '#e82626',
+ edgeCompleted: '#6acc6a',
+ edgeError: '#e82626',
+ edgeMemoryActive: '#e82626',
+ edgeToolActive: '#5a8cc8',
+ },
+};
+
export const useAppTheme = () => {
- const { isDarkMode } = useTheme();
+ const { theme } = useTheme();
+ const isDarkMode = DARK_BASE_THEMES.has(theme);
- const dynamicTheme = useMemo(() => {
+ return useMemo(() => {
+ const base = isDarkMode ? darkColors : lightColors;
+ const overrides = THEME_OVERRIDES[theme] ?? {};
return {
...baseTheme,
- colors: isDarkMode ? darkColors : lightColors,
+ colors: { ...base, ...overrides } as Colors,
isDarkMode,
};
- }, [isDarkMode]);
-
- return dynamicTheme;
+ }, [theme, isDarkMode]);
};
diff --git a/client/src/hooks/useSound.ts b/client/src/hooks/useSound.ts
new file mode 100644
index 00000000..d0ca3008
--- /dev/null
+++ b/client/src/hooks/useSound.ts
@@ -0,0 +1,56 @@
+/**
+ * useSound — React glue for the per-theme WebAudio engine.
+ *
+ * `useSoundSync()` mounts once at the Dashboard root. It:
+ * - mirrors the `soundEnabled` Zustand slice into `Sounds.setEnabled()`
+ * - reads `--sound-pack` from `:root` after every theme change and
+ * calls `Sounds.setPack(...)` so the active pack tracks the active
+ * theme without per-component wiring
+ *
+ * `useSound()` is the lightweight handle every event handler uses:
+ *
+ * const play = useSound();
+ * <button onClick={() => { play('click'); onSave(); }} />
+ *
+ * Adding a new sound event: extend `SoundEvent` in lib/sound.ts, add
+ * an entry per pack, and fire `play('<event>')` from the relevant
+ * handler. No additional wiring here.
+ */
+
+import { useEffect } from 'react';
+import { useTheme } from '../contexts/ThemeContext';
+import { useAppStore } from '../store/useAppStore';
+import { Sounds, type SoundPackName, type SoundEvent } from '../lib/sound';
+
+const VALID_PACKS: ReadonlySet<SoundPackName> = new Set([
+ 'none', 'parchment', 'marble', 'ink', 'clockwork', 'vibraphone',
+ 'terminal', 'scrap', 'crypt', 'bell', 'telex',
+]);
+
+function readSoundPack(): SoundPackName {
+ if (typeof document === 'undefined') return 'none';
+ const raw = getComputedStyle(document.documentElement)
+ .getPropertyValue('--sound-pack')
+ .trim()
+ .replace(/['"]/g, '');
+ return VALID_PACKS.has(raw as SoundPackName) ? (raw as SoundPackName) : 'none';
+}
+
+/** Mount once at the Dashboard root. */
+export function useSoundSync(): void {
+ const { theme } = useTheme();
+ const enabled = useAppStore((s) => s.soundEnabled);
+
+ useEffect(() => {
+ Sounds.setEnabled(enabled);
+ }, [enabled]);
+
+ useEffect(() => {
+ Sounds.setPack(readSoundPack());
+ }, [theme]);
+}
+
+/** Play handle. Returns the same `Sounds.play` reference each render. */
+export function useSound(): (event: SoundEvent) => void {
+ return Sounds.play;
+}
diff --git a/client/src/lib/sound.ts b/client/src/lib/sound.ts
new file mode 100644
index 00000000..da5f2149
--- /dev/null
+++ b/client/src/lib/sound.ts
@@ -0,0 +1,277 @@
+/**
+ * sound.ts — per-theme WebAudio sound packs.
+ *
+ * Synthesizes click / hover / type / success / error / run / save /
+ * modalOpen / modalClose events via a single OscillatorNode + GainNode
+ * per call. No external samples; no module-level audio context until
+ * the first play(). Off by default — toggle with `Sounds.setEnabled`.
+ *
+ * The active pack is selected by name (matches the per-theme
+ * `--sound-pack` CSS token). React glue lives in
+ * client/src/hooks/useSound.ts which:
+ * 1. Reads `--sound-pack` from `:root` whenever the active theme
+ * changes and calls `Sounds.setPack(...)`.
+ * 2. Wires `Sounds.setEnabled(...)` to the `soundEnabled` Zustand
+ * slice (persisted to localStorage as `machinaos-sound`).
+ *
+ * Ported from design_handoff_machinaos_themes/app/sound.js. The DOM
+ * autocapture (`document.addEventListener('click', ...)`) at the
+ * bottom of the upstream module is intentionally dropped — in React
+ * we fire `play()` from explicit handlers (ActionButton onClick,
+ * Modal open/close effect, etc.) so the side-effect surface is
+ * traceable.
+ */
+
+export type SoundEvent =
+ | 'click'
+ | 'hover'
+ | 'type'
+ | 'success'
+ | 'error'
+ | 'run'
+ | 'save'
+ | 'modalOpen'
+ | 'modalClose';
+
+export type SoundPackName =
+ | 'none'
+ | 'parchment'
+ | 'marble'
+ | 'ink'
+ | 'clockwork'
+ | 'vibraphone'
+ | 'terminal'
+ | 'scrap'
+ | 'crypt'
+ | 'bell'
+ | 'telex';
+
+interface OscConfig {
+ type: OscillatorType;
+ freq: number;
+ dur: number;
+ vol: number;
+ attack: number;
+ decay: number;
+ /** Optional low-pass filter cutoff (Hz). */
+ lp?: number;
+ /** Optional frequency sweep multiplier; final = freq * sweep. */
+ sweep?: number;
+}
+
+type EventTable = Partial<Record<SoundEvent, OscConfig>>;
+
+// Singleton AudioContext lazily constructed on first play.
+let audioCtx: AudioContext | null = null;
+function ensureCtx(): AudioContext | null {
+ if (audioCtx) return audioCtx;
+ try {
+ const Ctx = window.AudioContext || (window as any).webkitAudioContext;
+ if (!Ctx) return null;
+ audioCtx = new Ctx();
+ return audioCtx;
+ } catch {
+ return null;
+ }
+}
+
+let enabled = false;
+let activePackName: SoundPackName = 'none';
+let activePack: EventTable = {};
+
+function play(cfg: OscConfig | undefined): void {
+ if (!cfg || !enabled) return;
+ const ac = ensureCtx();
+ if (!ac) return;
+ // WebAudio context starts suspended on most browsers until a user
+ // gesture; resume() is a no-op once running.
+ if (ac.state === 'suspended') void ac.resume();
+ try {
+ const osc = ac.createOscillator();
+ const gain = ac.createGain();
+ osc.type = cfg.type;
+ osc.frequency.value = cfg.freq;
+ let target: AudioNode = osc;
+ if (cfg.lp) {
+ const lp = ac.createBiquadFilter();
+ lp.type = 'lowpass';
+ lp.frequency.value = cfg.lp;
+ target.connect(lp);
+ target = lp;
+ }
+ target.connect(gain);
+ gain.connect(ac.destination);
+ const now = ac.currentTime;
+ gain.gain.setValueAtTime(0, now);
+ gain.gain.linearRampToValueAtTime(cfg.vol, now + cfg.attack);
+ gain.gain.exponentialRampToValueAtTime(0.0001, now + cfg.attack + cfg.decay);
+ if (cfg.sweep) {
+ osc.frequency.exponentialRampToValueAtTime(cfg.freq * cfg.sweep, now + cfg.dur);
+ }
+ osc.start(now);
+ osc.stop(now + cfg.dur + 0.02);
+ } catch {
+ // WebAudio errors are non-fatal — silently drop.
+ }
+}
+
+// ── Sound packs ──────────────────────────────────────────────────────────
+//
+// Each pack maps each `SoundEvent` to an oscillator config. Volume is
+// kept ≤ 0.10 across the board so no pack clips. Configs are ported
+// verbatim from app/sound.js (handoff bundle).
+
+const PARCHMENT: EventTable = {
+ click: { type: 'sine', freq: 220, dur: 0.04, vol: 0.06, attack: 0.005, decay: 0.04 },
+ hover: { type: 'triangle', freq: 380, dur: 0.02, vol: 0.025, attack: 0.002, decay: 0.02 },
+ type: { type: 'square', freq: 180, dur: 0.025, vol: 0.04, attack: 0.001, decay: 0.025, lp: 800 },
+ success: { type: 'sine', freq: 523, dur: 0.4, vol: 0.08, attack: 0.01, decay: 0.4, sweep: 1.5 },
+ error: { type: 'sawtooth', freq: 110, dur: 0.25, vol: 0.10, attack: 0.005, decay: 0.25, lp: 600 },
+ run: { type: 'sine', freq: 392, dur: 0.18, vol: 0.10, attack: 0.01, decay: 0.18, sweep: 1.3 },
+ save: { type: 'triangle', freq: 294, dur: 0.3, vol: 0.10, attack: 0.02, decay: 0.3 },
+ modalOpen: { type: 'sine', freq: 392, dur: 0.18, vol: 0.07, attack: 0.02, decay: 0.18, sweep: 1.2 },
+ modalClose: { type: 'sine', freq: 392, dur: 0.14, vol: 0.06, attack: 0.005, decay: 0.14, sweep: 0.7 },
+};
+
+const MARBLE: EventTable = {
+ click: { type: 'sine', freq: 330, dur: 0.05, vol: 0.07, attack: 0.001, decay: 0.05 },
+ hover: { type: 'sine', freq: 520, dur: 0.02, vol: 0.025, attack: 0.001, decay: 0.02 },
+ type: { type: 'triangle', freq: 260, dur: 0.03, vol: 0.04, attack: 0.001, decay: 0.03, lp: 1200 },
+ success: { type: 'sine', freq: 392, dur: 0.5, vol: 0.09, attack: 0.005, decay: 0.5, sweep: 1.6 },
+ error: { type: 'sawtooth', freq: 130, dur: 0.30, vol: 0.10, attack: 0.005, decay: 0.30, lp: 500 },
+ run: { type: 'sine', freq: 440, dur: 0.22, vol: 0.10, attack: 0.005, decay: 0.22, sweep: 1.4 },
+ save: { type: 'sine', freq: 330, dur: 0.35, vol: 0.10, attack: 0.01, decay: 0.35 },
+ modalOpen: { type: 'sine', freq: 392, dur: 0.20, vol: 0.07, attack: 0.02, decay: 0.20, sweep: 1.3 },
+ modalClose: { type: 'sine', freq: 392, dur: 0.16, vol: 0.06, attack: 0.005, decay: 0.16, sweep: 0.7 },
+};
+
+const INK: EventTable = {
+ click: { type: 'triangle', freq: 280, dur: 0.05, vol: 0.05, attack: 0.005, decay: 0.05, lp: 1500 },
+ hover: { type: 'sine', freq: 440, dur: 0.018, vol: 0.02, attack: 0.001, decay: 0.018 },
+ type: { type: 'sine', freq: 220, dur: 0.04, vol: 0.04, attack: 0.005, decay: 0.04, lp: 600 },
+ success: { type: 'sine', freq: 660, dur: 1.2, vol: 0.08, attack: 0.01, decay: 1.2 },
+ error: { type: 'triangle', freq: 174, dur: 0.4, vol: 0.08, attack: 0.005, decay: 0.4, lp: 800 },
+ run: { type: 'sine', freq: 523, dur: 0.6, vol: 0.08, attack: 0.02, decay: 0.6 },
+ save: { type: 'sine', freq: 440, dur: 0.8, vol: 0.10, attack: 0.01, decay: 0.8 },
+ modalOpen: { type: 'sine', freq: 523, dur: 0.4, vol: 0.06, attack: 0.04, decay: 0.4 },
+ modalClose: { type: 'sine', freq: 392, dur: 0.4, vol: 0.05, attack: 0.005, decay: 0.4 },
+};
+
+const CLOCKWORK: EventTable = {
+ click: { type: 'square', freq: 800, dur: 0.04, vol: 0.06, attack: 0.001, decay: 0.04, lp: 2200 },
+ hover: { type: 'square', freq: 1100, dur: 0.012, vol: 0.02, attack: 0.001, decay: 0.012 },
+ type: { type: 'square', freq: 600, dur: 0.025, vol: 0.05, attack: 0.001, decay: 0.025, lp: 1800 },
+ success: { type: 'sawtooth', freq: 523, dur: 0.5, vol: 0.08, attack: 0.005, decay: 0.5, sweep: 1.5, lp: 2500 },
+ error: { type: 'sawtooth', freq: 196, dur: 0.35, vol: 0.10, attack: 0.005, decay: 0.35, lp: 700 },
+ run: { type: 'square', freq: 440, dur: 0.30, vol: 0.10, attack: 0.005, decay: 0.30, sweep: 1.4, lp: 2000 },
+ save: { type: 'triangle', freq: 660, dur: 0.45, vol: 0.10, attack: 0.01, decay: 0.45, lp: 2400 },
+ modalOpen: { type: 'square', freq: 392, dur: 0.18, vol: 0.07, attack: 0.005, decay: 0.18, sweep: 1.3, lp: 1800 },
+ modalClose: { type: 'square', freq: 392, dur: 0.14, vol: 0.06, attack: 0.005, decay: 0.14, sweep: 0.65, lp: 1400 },
+};
+
+const VIBRAPHONE: EventTable = {
+ click: { type: 'triangle', freq: 880, dur: 0.10, vol: 0.06, attack: 0.001, decay: 0.10 },
+ hover: { type: 'triangle', freq: 1320, dur: 0.05, vol: 0.025, attack: 0.001, decay: 0.05 },
+ type: { type: 'sine', freq: 660, dur: 0.06, vol: 0.04, attack: 0.001, decay: 0.06 },
+ success: { type: 'triangle', freq: 988, dur: 0.5, vol: 0.09, attack: 0.001, decay: 0.5, sweep: 1.5 },
+ error: { type: 'sawtooth', freq: 233, dur: 0.25, vol: 0.10, attack: 0.005, decay: 0.25, sweep: 0.6 },
+ run: { type: 'triangle', freq: 1175, dur: 0.30, vol: 0.10, attack: 0.001, decay: 0.30, sweep: 1.4 },
+ save: { type: 'triangle', freq: 880, dur: 0.40, vol: 0.10, attack: 0.001, decay: 0.40 },
+ modalOpen: { type: 'triangle', freq: 988, dur: 0.18, vol: 0.06, attack: 0.001, decay: 0.18, sweep: 1.4 },
+ modalClose: { type: 'triangle', freq: 988, dur: 0.18, vol: 0.06, attack: 0.001, decay: 0.18, sweep: 0.65 },
+};
+
+const TERMINAL: EventTable = {
+ click: { type: 'square', freq: 1200, dur: 0.025, vol: 0.06, attack: 0.001, decay: 0.025 },
+ hover: { type: 'square', freq: 1800, dur: 0.012, vol: 0.025, attack: 0.001, decay: 0.012 },
+ type: { type: 'square', freq: 880, dur: 0.018, vol: 0.05, attack: 0.0005, decay: 0.018 },
+ success: { type: 'square', freq: 1318, dur: 0.18, vol: 0.08, attack: 0.001, decay: 0.18, sweep: 1.5 },
+ error: { type: 'sawtooth', freq: 220, dur: 0.18, vol: 0.10, attack: 0.001, decay: 0.18, sweep: 0.5 },
+ run: { type: 'square', freq: 1568, dur: 0.10, vol: 0.10, attack: 0.001, decay: 0.10 },
+ save: { type: 'square', freq: 988, dur: 0.12, vol: 0.08, attack: 0.001, decay: 0.12, sweep: 1.2 },
+ modalOpen: { type: 'square', freq: 1175, dur: 0.06, vol: 0.06, attack: 0.001, decay: 0.06, sweep: 1.4 },
+ modalClose: { type: 'square', freq: 1175, dur: 0.06, vol: 0.06, attack: 0.001, decay: 0.06, sweep: 0.6 },
+};
+
+const SCRAP: EventTable = {
+ click: { type: 'sawtooth', freq: 180, dur: 0.05, vol: 0.07, attack: 0.0005, decay: 0.05, lp: 1400 },
+ hover: { type: 'sawtooth', freq: 320, dur: 0.012, vol: 0.025, attack: 0.0005, decay: 0.012, lp: 2000 },
+ type: { type: 'square', freq: 140, dur: 0.03, vol: 0.05, attack: 0.0005, decay: 0.03, lp: 800 },
+ success: { type: 'sawtooth', freq: 440, dur: 0.18, vol: 0.10, attack: 0.001, decay: 0.18, sweep: 1.3, lp: 1600 },
+ error: { type: 'sawtooth', freq: 90, dur: 0.5, vol: 0.12, attack: 0.001, decay: 0.5, lp: 400 },
+ run: { type: 'square', freq: 220, dur: 0.20, vol: 0.10, attack: 0.001, decay: 0.20, sweep: 1.2, lp: 1200 },
+ save: { type: 'sawtooth', freq: 330, dur: 0.18, vol: 0.10, attack: 0.001, decay: 0.18, lp: 1400 },
+ modalOpen: { type: 'sawtooth', freq: 196, dur: 0.10, vol: 0.07, attack: 0.001, decay: 0.10, lp: 1000 },
+ modalClose: { type: 'sawtooth', freq: 196, dur: 0.08, vol: 0.06, attack: 0.001, decay: 0.08, sweep: 0.5, lp: 700 },
+};
+
+const CRYPT: EventTable = {
+ click: { type: 'sine', freq: 220, dur: 0.08, vol: 0.06, attack: 0.005, decay: 0.08, lp: 600 },
+ hover: { type: 'sine', freq: 330, dur: 0.025, vol: 0.02, attack: 0.005, decay: 0.025, lp: 800 },
+ type: { type: 'sine', freq: 165, dur: 0.04, vol: 0.04, attack: 0.005, decay: 0.04, lp: 400 },
+ success: { type: 'triangle', freq: 261, dur: 0.8, vol: 0.08, attack: 0.02, decay: 0.8, sweep: 1.5, lp: 1200 },
+ error: { type: 'sawtooth', freq: 73, dur: 0.6, vol: 0.10, attack: 0.01, decay: 0.6, lp: 300 },
+ run: { type: 'sine', freq: 196, dur: 0.45, vol: 0.10, attack: 0.02, decay: 0.45, sweep: 1.3, lp: 800 },
+ save: { type: 'sine', freq: 174, dur: 0.7, vol: 0.10, attack: 0.05, decay: 0.7, lp: 700 },
+ modalOpen: { type: 'sine', freq: 220, dur: 0.5, vol: 0.07, attack: 0.05, decay: 0.5, lp: 600 },
+ modalClose: { type: 'sine', freq: 220, dur: 0.4, vol: 0.06, attack: 0.005, decay: 0.4, sweep: 0.6, lp: 500 },
+};
+
+const BELL: EventTable = {
+ click: { type: 'triangle', freq: 392, dur: 0.10, vol: 0.06, attack: 0.001, decay: 0.10, lp: 1500 },
+ hover: { type: 'sine', freq: 660, dur: 0.025, vol: 0.025, attack: 0.001, decay: 0.025 },
+ type: { type: 'square', freq: 220, dur: 0.025, vol: 0.04, attack: 0.001, decay: 0.025, lp: 800 },
+ success: { type: 'triangle', freq: 523, dur: 1.0, vol: 0.09, attack: 0.001, decay: 1.0 },
+ error: { type: 'sawtooth', freq: 110, dur: 0.6, vol: 0.10, attack: 0.005, decay: 0.6, lp: 500 },
+ run: { type: 'triangle', freq: 440, dur: 0.6, vol: 0.10, attack: 0.001, decay: 0.6 },
+ save: { type: 'triangle', freq: 392, dur: 0.9, vol: 0.10, attack: 0.001, decay: 0.9 },
+ modalOpen: { type: 'triangle', freq: 523, dur: 0.4, vol: 0.07, attack: 0.001, decay: 0.4 },
+ modalClose: { type: 'triangle', freq: 392, dur: 0.4, vol: 0.06, attack: 0.001, decay: 0.4 },
+};
+
+const TELEX: EventTable = {
+ click: { type: 'square', freq: 1500, dur: 0.012, vol: 0.07, attack: 0.0005, decay: 0.012 },
+ hover: { type: 'square', freq: 2200, dur: 0.006, vol: 0.02, attack: 0.0005, decay: 0.006 },
+ type: { type: 'square', freq: 1100, dur: 0.010, vol: 0.05, attack: 0.0005, decay: 0.010 },
+ success: { type: 'square', freq: 1318, dur: 0.10, vol: 0.08, attack: 0.0005, decay: 0.10 },
+ error: { type: 'sawtooth', freq: 220, dur: 0.4, vol: 0.12, attack: 0.0005, decay: 0.4 },
+ run: { type: 'square', freq: 1760, dur: 0.06, vol: 0.10, attack: 0.0005, decay: 0.06 },
+ save: { type: 'square', freq: 1175, dur: 0.08, vol: 0.08, attack: 0.0005, decay: 0.08 },
+ modalOpen: { type: 'square', freq: 988, dur: 0.05, vol: 0.07, attack: 0.0005, decay: 0.05 },
+ modalClose: { type: 'square', freq: 988, dur: 0.04, vol: 0.06, attack: 0.0005, decay: 0.04, sweep: 0.6 },
+};
+
+const PACKS: Record<SoundPackName, EventTable> = {
+ none: {},
+ parchment: PARCHMENT,
+ marble: MARBLE,
+ ink: INK,
+ clockwork: CLOCKWORK,
+ vibraphone: VIBRAPHONE,
+ terminal: TERMINAL,
+ scrap: SCRAP,
+ crypt: CRYPT,
+ bell: BELL,
+ telex: TELEX,
+};
+
+// ── Public API ───────────────────────────────────────────────────────────
+
+export const Sounds = {
+ setEnabled(value: boolean): void {
+ enabled = value;
+ },
+ isEnabled(): boolean {
+ return enabled;
+ },
+ setPack(name: SoundPackName): void {
+ activePackName = name;
+ activePack = PACKS[name] ?? PACKS.none;
+ },
+ pack(): SoundPackName {
+ return activePackName;
+ },
+ play(event: SoundEvent): void {
+ play(activePack[event]);
+ },
+};
diff --git a/client/src/main.tsx b/client/src/main.tsx
index 789c446c..5b0de392 100644
--- a/client/src/main.tsx
+++ b/client/src/main.tsx
@@ -10,8 +10,18 @@ import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import './themes/base.css'
import './themes/light.css'
import './themes/dark.css'
+// Utopian set
import './themes/renaissance.css'
+import './themes/greek.css'
+import './themes/edo.css'
+import './themes/steampunk.css'
+import './themes/atomic.css'
+// Dystopian set
import './themes/cyber.css'
+import './themes/wasteland.css'
+import './themes/rot.css'
+import './themes/plague.css'
+import './themes/surveillance.css'
import './index.css'
import App from './App'
import { ThemeProvider } from './contexts/ThemeContext'
diff --git a/client/src/store/useAppStore.ts b/client/src/store/useAppStore.ts
index 9e7c10cd..917c5808 100644
--- a/client/src/store/useAppStore.ts
+++ b/client/src/store/useAppStore.ts
@@ -49,6 +49,10 @@ interface AppStore {
componentPaletteVisible: boolean;
consolePanelVisible: boolean;
proMode: boolean; // false = noob mode (only AI categories), true = pro mode (all categories)
+ /** WebAudio sound effects toggle (per-theme pack picked from
+ * --sound-pack CSS token by `useSoundSync()`). Persisted to
+ * localStorage as `machinaos-sound`; default off (opt-in). */
+ soundEnabled: boolean;
renamingNodeId: string | null;
// Workflow actions
@@ -65,6 +69,8 @@ interface AppStore {
toggleSidebar: () => void;
toggleComponentPalette: () => void;
toggleProMode: () => void;
+ setSoundEnabled: (enabled: boolean) => void;
+ toggleSoundEnabled: () => void;
setRenamingNodeId: (nodeId: string | null) => void;
// UI defaults from database
@@ -130,6 +136,10 @@ const STORAGE_KEYS = {
componentPaletteVisible: 'ui_component_palette_visible',
consolePanelVisible: 'ui_console_panel_visible',
proMode: 'ui_pro_mode',
+ /** Sound enabled key — matches the design handoff's
+ * `localStorage['machinaos-sound']` convention so a returning user's
+ * prior choice rehydrates regardless of which session set it. */
+ soundEnabled: 'machinaos-sound',
};
// Helper to load boolean from localStorage
@@ -163,6 +173,7 @@ export const useAppStore = create<AppStore>((set, get) => ({
componentPaletteVisible: loadBooleanFromStorage(STORAGE_KEYS.componentPaletteVisible, true),
consolePanelVisible: loadBooleanFromStorage(STORAGE_KEYS.consolePanelVisible, false),
proMode: loadBooleanFromStorage(STORAGE_KEYS.proMode, false), // Default to noob mode
+ soundEnabled: loadBooleanFromStorage(STORAGE_KEYS.soundEnabled, false), // Opt-in default
renamingNodeId: null,
// Workflow management
@@ -331,6 +342,18 @@ export const useAppStore = create<AppStore>((set, get) => ({
});
},
+ setSoundEnabled: (enabled) => {
+ saveBooleanToStorage(STORAGE_KEYS.soundEnabled, enabled);
+ set({ soundEnabled: enabled });
+ },
+ toggleSoundEnabled: () => {
+ set((state) => {
+ const newValue = !state.soundEnabled;
+ saveBooleanToStorage(STORAGE_KEYS.soundEnabled, newValue);
+ return { soundEnabled: newValue };
+ });
+ },
+
setRenamingNodeId: (nodeId) => {
set({ renamingNodeId: nodeId });
},
diff --git a/client/src/styles/theme.ts b/client/src/styles/theme.ts
index 32768633..4082b073 100644
--- a/client/src/styles/theme.ts
+++ b/client/src/styles/theme.ts
@@ -1,23 +1,33 @@
-// Unified theme system - consolidated design tokens and component styles
+// Theme constants — exported for the canvas + maps surface and the
+// useAppTheme overlay map.
//
-// PHASE-OUT NOTICE (Phase 3 of docs-internal/ui_migration_plan.md):
-// The single source of truth for color tokens is the :root / .dark
-// blocks in client/src/index.css. New components SHOULD prefer Tailwind
-// utility classes (e.g. `bg-dracula-green`, `text-foreground`,
-// `bg-dracula-orange/15`) over reading these TS exports.
+// SCOPE (post-Wave-14):
+// - `lightColors` / `darkColors` are the two BASE PACKS. The 10-way
+// `THEME_OVERRIDES` map in `client/src/hooks/useAppTheme.ts` merges
+// a per-theme overlay (primary, focus, action palette, edge stroke
+// palette) on top of whichever base pack matches the active theme's
+// dark / light family — see `theme_system.md` for the contract.
+// - `dracula` / `solarized` raw palette constants stay for cases a
+// Tailwind class can't express: SVG `fill=`, React Flow JS edge
+// styles, prismjs token CSS strings, MapSelector / GoogleMaps SDK
+// JS-side colors.
+// - `spacing` / `fontSize` / `fontWeight` / `nodeSize` / `iconSize` /
+// `buttonSize` / `layout` / `transitions` / `constants` stay too —
+// these are not color tokens; they back the canvas-animation engine
+// and a few non-color UI primitives.
//
-// Migration cheatsheet:
-// theme.dracula.green -> className="text-dracula-green"
-// { backgroundColor: theme.dracula.X } -> className="bg-dracula-X"
-// { color: theme.colors.text } -> className="text-foreground"
-// { backgroundColor: theme.colors.X } -> className="bg-{token}"
-// theme.dracula.X + '25' -> className="bg-dracula-X/15"
+// AUTHORITATIVE SOURCE for color tokens: the `:root[data-theme="..."]`
+// blocks in `client/src/themes/<name>.css` (10 themes) plus the shadcn
+// HSL-triplet bridge in `client/src/index.css`. New components consume
+// those via Tailwind utilities (`bg-bg-app`, `text-fg-default`,
+// `bg-action-run-soft`, `bg-node-agent-soft`) — never `theme.colors.X`
+// directly except inside `useAppTheme` consumers (canvas + maps).
//
-// The `dracula` and `solarized` constants stay for cases a Tailwind
-// class can't express (SVG `fill=`, react-flow JS edge styles, prismjs
-// token CSS strings). Spacing / fontSize / fontWeight / nodeSize /
-// iconSize / buttonSize / layout / transitions / constants stay too —
-// they are not color tokens.
+// Migration cheatsheet for any remaining sites that read this file:
+// theme.dracula.green -> className="text-dracula-green"
+// { backgroundColor: theme.dracula.X } -> className="bg-dracula-X"
+// { color: theme.colors.text } -> className="text-foreground" or "text-fg-default"
+// { backgroundColor: theme.colors.X } -> className="bg-{token}" or "bg-bg-app"
// ============================================================================
// DRACULA COLOR PALETTE (vibrant action colors + dark theme backgrounds)
diff --git a/client/src/themes/atomic.css b/client/src/themes/atomic.css
new file mode 100644
index 00000000..9898451b
--- /dev/null
+++ b/client/src/themes/atomic.css
@@ -0,0 +1,130 @@
+/* ============================================================================
+ * themes/atomic.css — 1962 Eames optimism. Cream, atomic orange, turquoise,
+ * slate. Boomerangs and starbursts. Reads like a vintage NASA brochure.
+ * Ported from design_handoff_machinaos_themes/themes/atomic.css.
+ * ============================================================================ */
+
+:root[data-theme="atomic"] {
+ --bg-app: #f0e6d2;
+ --bg-panel: #faf2dc;
+ --bg-canvas: #e8dcc0;
+ --bg-elevated: #ffffff;
+ --bg-input: #ffffff;
+ --bg-hover: rgba(232, 90, 38, 0.08);
+ --bg-active: rgba(232, 90, 38, 0.18);
+ --bg-overlay: rgba(40, 30, 20, 0.5);
+
+ --border-default: #c8b890;
+ --border-strong: #2a3a4a;
+ --border-focus: #e85a26;
+ --ornament-frame: none;
+
+ --fg-default: #2a3a4a;
+ --fg-muted: #5a6a7a;
+ --fg-faint: #8a9aaa;
+ --fg-on-accent: #faf2dc;
+ --fg-on-success: #faf2dc;
+ --fg-on-danger: #faf2dc;
+ --fg-on-warning: #2a3a4a;
+
+ --turquoise: #3a9aa0;
+ --mustard: #d8a838;
+ --slate: #2a3a4a;
+ --atomic-orange: #e85a26;
+
+ --font-display: 'Bevan', 'Alfa Slab One', serif;
+ --font-body: 'Lato', 'Helvetica Neue', sans-serif;
+ --font-mono: 'Space Mono', 'JetBrains Mono', monospace;
+ --type-scale-base: 14px;
+ --type-tracking-display: 0.06em;
+ --type-uppercase: uppercase;
+
+ --radius-sm: 0px;
+ --radius-md: 2px;
+ --radius-lg: 4px;
+ --radius-pill: 999px;
+
+ --dur-fast: 100ms;
+ --dur-default: 200ms;
+ --dur-slow: 380ms;
+ --ease-default: cubic-bezier(0.34, 1.6, 0.5, 1);
+ --ease-emphasis: cubic-bezier(0.34, 1.6, 0.5, 1);
+ --motion-style: bouncy;
+ --sound-pack: vibraphone;
+
+ --cursor-default: auto;
+ --cursor-pointer: pointer;
+ --scrollbar-track: #f0e6d2;
+ --scrollbar-thumb: #2a3a4a;
+
+ /* Shadcn HSL bridge */
+ --background: 41 47% 88%;
+ --foreground: 213 27% 23%;
+ --card: 0 0% 100%;
+ --card-foreground: 213 27% 23%;
+ --popover: 0 0% 100%;
+ --popover-foreground: 213 27% 23%;
+
+ --primary: 14 81% 53%; /* atomic orange */
+ --primary-foreground: 41 80% 92%;
+ --secondary: 44 83% 92%;
+ --secondary-foreground: 213 27% 23%;
+ --muted: 44 83% 92%;
+ --muted-foreground: 211 14% 42%;
+ --accent: 184 46% 43%; /* turquoise */
+ --accent-foreground: 213 27% 23%;
+
+ --destructive: 14 81% 53%;
+ --destructive-foreground: 41 80% 92%;
+ --success: 120 21% 45%;
+ --warning: 41 67% 53%;
+ --info: 184 46% 43%;
+
+ --border: 213 27% 23%;
+ --input: 40 33% 67%;
+ --ring: 14 81% 53%;
+
+ /* Action role bridge */
+ --action-run: 120 21% 45%;
+ --action-run-soft: 120 21% 45% / 0.16;
+ --action-run-hover: 120 21% 45% / 0.30;
+ --action-run-border: 120 21% 45% / 0.7;
+
+ --action-stop: 14 81% 53%;
+ --action-stop-soft: 14 81% 53% / 0.16;
+ --action-stop-hover: 14 81% 53% / 0.30;
+ --action-stop-border: 14 81% 53% / 0.7;
+
+ --action-save: 14 81% 53%;
+ --action-save-soft: 14 81% 53% / 0.18;
+ --action-save-hover: 14 81% 53% / 0.32;
+ --action-save-border: 14 81% 53% / 0.7;
+
+ --action-config: 41 67% 53%;
+ --action-config-soft: 41 67% 53% / 0.18;
+ --action-config-hover: 41 67% 53% / 0.32;
+ --action-config-border: 41 67% 53% / 0.7;
+
+ --action-secret: 184 46% 43%;
+ --action-secret-soft: 184 46% 43% / 0.16;
+ --action-secret-hover: 184 46% 43% / 0.30;
+ --action-secret-border: 184 46% 43% / 0.7;
+
+ --action-tools: 184 46% 43%;
+ --action-tools-soft: 184 46% 43% / 0.16;
+ --action-tools-hover: 184 46% 43% / 0.30;
+ --action-tools-border: 184 46% 43% / 0.6;
+
+ --tint-soft: 14%;
+ --tint-border: 35%;
+}
+
+/* Body — clean cardstock; starburst lives on canvas in W2 wrapper */
+:root[data-theme="atomic"] body {
+ background: var(--bg-app);
+}
+
+:root[data-theme="atomic"] ::selection {
+ background: rgba(232, 90, 38, 0.4);
+ color: #2a3a4a;
+}
diff --git a/client/src/themes/edo.css b/client/src/themes/edo.css
new file mode 100644
index 00000000..afb5b78d
--- /dev/null
+++ b/client/src/themes/edo.css
@@ -0,0 +1,134 @@
+/* ============================================================================
+ * themes/edo.css — washi paper, sumi-e ink, vermillion hanko seal.
+ *
+ * Quiet, asymmetric, lots of negative space. Reads like an ink-painting on
+ * rice paper. Ported from design_handoff_machinaos_themes/themes/edo.css.
+ * ============================================================================ */
+
+:root[data-theme="edo"] {
+ --bg-app: #f4ecd8;
+ --bg-panel: #faf3e0;
+ --bg-canvas: #ede4ca;
+ --bg-elevated: #fdf8ea;
+ --bg-input: #fdf8ea;
+ --bg-hover: rgba(180, 30, 30, 0.06);
+ --bg-active: rgba(180, 30, 30, 0.14);
+ --bg-overlay: rgba(40, 30, 20, 0.55);
+
+ --border-default: #c8b890;
+ --border-strong: #1a1410;
+ --border-focus: #b41e1e;
+ --ornament-frame: none;
+
+ --fg-default: #1a1410;
+ --fg-muted: #6a5e48;
+ --fg-faint: #a89a78;
+ --fg-on-accent: #fdf8ea;
+ --fg-on-success: #fdf8ea;
+ --fg-on-danger: #fdf8ea;
+ --fg-on-warning: #1a1410;
+
+ --sumi: #1a1410;
+ --sakura: #e89aa8;
+ --bamboo: #4a6a3a;
+ --tea: #8a6a3a;
+ --vermillion: #b41e1e;
+
+ --font-display: 'Shippori Mincho', 'Sawarabi Mincho', 'Noto Serif JP', serif;
+ --font-body: 'Shippori Mincho', 'Sawarabi Mincho', 'Noto Serif JP', serif;
+ --font-mono: 'JetBrains Mono', monospace;
+ --type-scale-base: 14px;
+ --type-tracking-display: 0.06em;
+ --type-uppercase: none;
+
+ --radius-sm: 0px;
+ --radius-md: 0px;
+ --radius-lg: 0px;
+ --radius-pill: 0px;
+
+ --dur-fast: 90ms;
+ --dur-default: 220ms;
+ --dur-slow: 520ms;
+ --ease-default: cubic-bezier(0.4, 0, 0.2, 1);
+ --ease-emphasis: cubic-bezier(0.7, -0.1, 0.3, 1.2);
+ --motion-style: organic;
+ --sound-pack: ink;
+
+ --cursor-default: auto;
+ --cursor-pointer: pointer;
+ --scrollbar-track: #f4ecd8;
+ --scrollbar-thumb: #c8b890;
+
+ /* Shadcn HSL bridge */
+ --background: 41 56% 90%;
+ --foreground: 24 25% 8%;
+ --card: 44 80% 96%;
+ --card-foreground: 24 25% 8%;
+ --popover: 44 80% 96%;
+ --popover-foreground: 24 25% 8%;
+
+ --primary: 0 71% 41%; /* vermillion */
+ --primary-foreground: 44 80% 96%;
+ --secondary: 44 71% 93%;
+ --secondary-foreground: 24 25% 8%;
+ --muted: 44 71% 93%;
+ --muted-foreground: 36 19% 35%;
+ --accent: 0 71% 41%;
+ --accent-foreground: 44 80% 96%;
+
+ --destructive: 0 71% 41%;
+ --destructive-foreground: 44 80% 96%;
+ --success: 100 29% 32%; /* bamboo */
+ --warning: 41 60% 49%;
+ --info: 24 25% 8%; /* sumi black for info */
+
+ --border: 24 25% 8%;
+ --input: 40 35% 67%;
+ --ring: 0 71% 41%;
+
+ /* Action role bridge */
+ --action-run: 100 29% 32%;
+ --action-run-soft: 100 29% 32% / 0.14;
+ --action-run-hover: 100 29% 32% / 0.26;
+ --action-run-border: 100 29% 32% / 0.7;
+
+ --action-stop: 0 71% 41%;
+ --action-stop-soft: 0 71% 41% / 0.14;
+ --action-stop-hover: 0 71% 41% / 0.28;
+ --action-stop-border: 0 71% 41% / 0.7;
+
+ --action-save: 0 71% 41%;
+ --action-save-soft: 0 71% 41% / 0.16;
+ --action-save-hover: 0 71% 41% / 0.30;
+ --action-save-border: 0 71% 41% / 0.7;
+
+ --action-config: 41 60% 49%;
+ --action-config-soft: 41 60% 49% / 0.16;
+ --action-config-hover: 41 60% 49% / 0.28;
+ --action-config-border: 41 60% 49% / 0.6;
+
+ --action-secret: 24 25% 8%;
+ --action-secret-soft: 24 25% 8% / 0.10;
+ --action-secret-hover: 24 25% 8% / 0.20;
+ --action-secret-border: 24 25% 8% / 0.5;
+
+ --action-tools: 100 29% 32%;
+ --action-tools-soft: 100 29% 32% / 0.14;
+ --action-tools-hover: 100 29% 32% / 0.26;
+ --action-tools-border: 100 29% 32% / 0.6;
+
+ --tint-soft: 10%;
+ --tint-border: 30%;
+}
+
+/* Body washi texture */
+:root[data-theme="edo"] body {
+ background:
+ url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='300' height='300'><filter id='w'><feTurbulence baseFrequency='0.85' numOctaves='1'/><feColorMatrix values='0 0 0 0 0.65 0 0 0 0 0.55 0 0 0 0 0.35 0 0 0 0.06 0'/></filter><rect width='300' height='300' filter='url(%23w)'/></svg>"),
+ var(--bg-app);
+}
+
+:root[data-theme="edo"] ::selection {
+ background: rgba(180, 30, 30, 0.30);
+ color: #1a1410;
+}
diff --git a/client/src/themes/greek.css b/client/src/themes/greek.css
new file mode 100644
index 00000000..286409ff
--- /dev/null
+++ b/client/src/themes/greek.css
@@ -0,0 +1,167 @@
+/* ============================================================================
+ * themes/greek.css — sun-bleached marble agora.
+ *
+ * Lapis blue + oxblood + gold meander on cracked Aegean marble.
+ * Ported from design_handoff_machinaos_themes/themes/greek.css.
+ *
+ * Decorative class-targeted rules (.toolbar, .sidebar, .canvas, .modal,
+ * .cmdk, etc.) activate once Wave 2 adds those structural classes to
+ * the React tree. Token block alone retints existing chrome via the
+ * shadcn HSL bridge.
+ * ============================================================================ */
+
+:root[data-theme="greek"] {
+ /* ── New contract ─────────────────────────────────────────────────── */
+
+ --bg-app: #ede5d0;
+ --bg-panel: #f5efde;
+ --bg-canvas: #e6dcc2;
+ --bg-elevated: #faf6e9;
+ --bg-input: #faf6e9;
+ --bg-hover: rgba(40, 75, 130, 0.08);
+ --bg-active: rgba(40, 75, 130, 0.16);
+ --bg-overlay: rgba(60, 50, 30, 0.55);
+
+ --border-default: #b8a878;
+ --border-strong: #4a3818;
+ --border-focus: #284b82;
+ --ornament-frame: none;
+
+ --fg-default: #2a2415;
+ --fg-muted: #6a5d3c;
+ --fg-faint: #998c64;
+ --fg-on-accent: #faf6e9;
+ --fg-on-success: #faf6e9;
+ --fg-on-danger: #faf6e9;
+ --fg-on-warning: #2a2415;
+
+ --accent: #284b82;
+ --accent-hover: #3a5fa0;
+ --marble-vein: #d8c89a;
+ --oxblood: #7a1a18;
+ --olive: #6a7a32;
+ --gold: #c8a040;
+
+ --font-display: 'Cinzel', 'Trajan Pro', serif;
+ --font-body: 'Cormorant Garamond', 'Times New Roman', serif;
+ --font-mono: 'Courier Prime', 'Courier New', monospace;
+ --type-scale-base: 14px;
+ --type-tracking-display: 0.18em;
+ --type-uppercase: uppercase;
+
+ --radius-sm: 0px;
+ --radius-md: 0px;
+ --radius-lg: 2px;
+ --radius-pill: 0px;
+
+ --dur-fast: 120ms;
+ --dur-default: 240ms;
+ --dur-slow: 460ms;
+ --ease-default: cubic-bezier(0.3, 0.7, 0.4, 1);
+ --ease-emphasis: cubic-bezier(0.6, -0.05, 0.3, 1.4);
+ --motion-style: smooth;
+ --sound-pack: marble;
+
+ --cursor-default: auto;
+ --cursor-pointer: pointer;
+ --scrollbar-track: #ede5d0;
+ --scrollbar-thumb: #b8a878;
+
+ /* ── Shadcn HSL bridge ────────────────────────────────────────────── */
+
+ --background: 42 38% 87%;
+ --foreground: 38 33% 12%;
+ --card: 46 71% 95%;
+ --card-foreground: 38 33% 12%;
+ --popover: 46 71% 95%;
+ --popover-foreground: 38 33% 12%;
+
+ --primary: 217 53% 33%; /* lapis */
+ --primary-foreground: 46 71% 95%;
+ --secondary: 44 60% 91%;
+ --secondary-foreground: 38 33% 12%;
+ --muted: 44 60% 91%;
+ --muted-foreground: 40 28% 33%;
+ --accent: 41 56% 52%; /* gold for shadcn accent (overrides new-contract --accent string above for HSL only — Tailwind utilities) */
+ --accent-foreground: 38 33% 12%;
+
+ --destructive: 1 66% 29%; /* oxblood */
+ --destructive-foreground: 46 71% 95%;
+ --success: 71 41% 33%; /* olive */
+ --warning: 41 56% 52%; /* gold */
+ --info: 217 53% 33%; /* lapis */
+
+ --border: 33 51% 19%; /* border-strong drives the visible borders */
+ --input: 40 33% 60%;
+ --ring: 217 53% 33%;
+
+ /* ── Action role bridge ───────────────────────────────────────────── */
+
+ --action-run: 71 41% 33%;
+ --action-run-soft: 71 41% 33% / 0.18;
+ --action-run-hover: 71 41% 33% / 0.30;
+ --action-run-border: 71 41% 33% / 0.7;
+
+ --action-stop: 1 66% 29%;
+ --action-stop-soft: 1 66% 29% / 0.16;
+ --action-stop-hover: 1 66% 29% / 0.28;
+ --action-stop-border: 1 66% 29% / 0.7;
+
+ --action-save: 41 56% 52%;
+ --action-save-soft: 41 56% 52% / 0.20;
+ --action-save-hover: 41 56% 52% / 0.35;
+ --action-save-border: 41 56% 52% / 0.7;
+
+ --action-config: 41 56% 52%;
+ --action-config-soft: 41 56% 52% / 0.18;
+ --action-config-hover: 41 56% 52% / 0.30;
+ --action-config-border: 41 56% 52% / 0.6;
+
+ --action-secret: 217 53% 33%;
+ --action-secret-soft: 217 53% 33% / 0.14;
+ --action-secret-hover: 217 53% 33% / 0.26;
+ --action-secret-border: 217 53% 33% / 0.7;
+
+ --action-tools: 217 53% 33%;
+ --action-tools-soft: 217 53% 33% / 0.14;
+ --action-tools-hover: 217 53% 33% / 0.26;
+ --action-tools-border: 217 53% 33% / 0.7;
+
+ --tint-soft: 14%;
+ --tint-border: 35%;
+}
+
+/* ── Body marble texture ──────────────────────────────────────────────── */
+
+:root[data-theme="greek"] body {
+ background:
+ url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='400' height='400'><filter id='m'><feTurbulence baseFrequency='0.012 0.04' numOctaves='2' seed='3'/><feColorMatrix values='0 0 0 0 0.85 0 0 0 0 0.78 0 0 0 0 0.61 0 0 0 0.18 0'/></filter><rect width='400' height='400' filter='url(%23m)'/></svg>"),
+ var(--bg-app);
+}
+
+/* ── Decorative rules (activate after Wave 2 wrappers land) ──────────── */
+
+:root[data-theme="greek"] .toolbar,
+:root[data-theme="greek"] .sidebar,
+:root[data-theme="greek"] .palette,
+:root[data-theme="greek"] .chat {
+ background:
+ url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='400' height='400'><filter id='m'><feTurbulence baseFrequency='0.014 0.05' numOctaves='2' seed='7'/><feColorMatrix values='0 0 0 0 0.85 0 0 0 0 0.78 0 0 0 0 0.61 0 0 0 0.14 0'/></filter><rect width='400' height='400' filter='url(%23m)'/></svg>"),
+ var(--bg-panel);
+}
+
+:root[data-theme="greek"] .canvas-host {
+ background:
+ url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='80' height='80'><g fill='none' stroke='%234a3818' stroke-width='0.4' opacity='0.18'><path d='M0 40 H10 V20 H30 V60 H50 V20 H70 V40 H80'/></g></svg>"),
+ var(--bg-canvas);
+}
+
+:root[data-theme="greek"] .modal-frame {
+ border: 4px double var(--border-strong) !important;
+}
+
+::selection {}
+:root[data-theme="greek"] ::selection {
+ background: rgba(40, 75, 130, 0.4);
+ color: #2a2415;
+}
diff --git a/client/src/themes/plague.css b/client/src/themes/plague.css
new file mode 100644
index 00000000..837e9a81
--- /dev/null
+++ b/client/src/themes/plague.css
@@ -0,0 +1,134 @@
+/* ============================================================================
+ * themes/plague.css — quarantine notices nailed to bleached doors.
+ *
+ * Sickly green-yellow on cold blue, biohazard red, official red wax seals.
+ * Reads like the WHO in 1349. Ported from
+ * design_handoff_machinaos_themes/themes/plague.css.
+ * ============================================================================ */
+
+:root[data-theme="plague"] {
+ --bg-app: #d8d4c0;
+ --bg-panel: #e4dfc8;
+ --bg-canvas: #c8c4b0;
+ --bg-elevated: #efeacf;
+ --bg-input: #efeacf;
+ --bg-hover: rgba(120, 60, 40, 0.10);
+ --bg-active: rgba(120, 60, 40, 0.20);
+ --bg-overlay: rgba(40, 30, 24, 0.6);
+
+ --border-default: #a89478;
+ --border-strong: #2a1c14;
+ --border-focus: #783c28;
+ --ornament-frame: none;
+
+ --fg-default: #2a1c14;
+ --fg-muted: #6a5440;
+ --fg-faint: #98886a;
+ --fg-on-accent: #efeacf;
+ --fg-on-success: #efeacf;
+ --fg-on-danger: #efeacf;
+ --fg-on-warning: #2a1c14;
+
+ --bile: #98a838;
+ --crow: #1a1410;
+ --linen: #efeacf;
+ --dried-blood: #783c28;
+
+ --font-display: 'UnifrakturCook', 'UnifrakturMaguntia', serif;
+ --font-body: 'EB Garamond', 'Cormorant Garamond', serif;
+ --font-mono: 'Special Elite', monospace;
+ --type-scale-base: 14px;
+ --type-tracking-display: 0.06em;
+ --type-uppercase: uppercase;
+
+ --radius-sm: 0px;
+ --radius-md: 0px;
+ --radius-lg: 0px;
+ --radius-pill: 0px;
+
+ --dur-fast: 100ms;
+ --dur-default: 220ms;
+ --dur-slow: 460ms;
+ --ease-default: cubic-bezier(0.4, 0, 0.6, 1);
+ --ease-emphasis: cubic-bezier(0.4, 0, 0.6, 1);
+ --motion-style: stiff;
+ --sound-pack: bell;
+
+ --cursor-default: auto;
+ --cursor-pointer: pointer;
+ --scrollbar-track: #d8d4c0;
+ --scrollbar-thumb: #2a1c14;
+
+ /* Shadcn HSL bridge */
+ --background: 49 25% 80%;
+ --foreground: 24 35% 12%;
+ --card: 47 53% 88%;
+ --card-foreground: 24 35% 12%;
+ --popover: 47 53% 88%;
+ --popover-foreground: 24 35% 12%;
+
+ --primary: 14 50% 31%; /* dried blood */
+ --primary-foreground: 47 53% 88%;
+ --secondary: 49 35% 84%;
+ --secondary-foreground: 24 35% 12%;
+ --muted: 49 35% 84%;
+ --muted-foreground: 28 26% 33%;
+ --accent: 65 49% 44%; /* bile */
+ --accent-foreground: 24 35% 12%;
+
+ --destructive: 14 50% 31%;
+ --destructive-foreground: 47 53% 88%;
+ --success: 75 47% 30%;
+ --warning: 65 49% 44%;
+ --info: 213 17% 35%;
+
+ --border: 24 35% 12%;
+ --input: 33 30% 56%;
+ --ring: 14 50% 31%;
+
+ /* Action role bridge */
+ --action-run: 75 47% 30%;
+ --action-run-soft: 75 47% 30% / 0.20;
+ --action-run-hover: 75 47% 30% / 0.34;
+ --action-run-border: 75 47% 30% / 0.7;
+
+ --action-stop: 14 50% 31%;
+ --action-stop-soft: 14 50% 31% / 0.20;
+ --action-stop-hover: 14 50% 31% / 0.34;
+ --action-stop-border: 14 50% 31% / 0.7;
+
+ --action-save: 14 50% 31%;
+ --action-save-soft: 14 50% 31% / 0.18;
+ --action-save-hover: 14 50% 31% / 0.32;
+ --action-save-border: 14 50% 31% / 0.7;
+
+ --action-config: 65 49% 44%;
+ --action-config-soft: 65 49% 44% / 0.20;
+ --action-config-hover: 65 49% 44% / 0.34;
+ --action-config-border: 65 49% 44% / 0.6;
+
+ --action-secret: 213 17% 35%;
+ --action-secret-soft: 213 17% 35% / 0.16;
+ --action-secret-hover: 213 17% 35% / 0.30;
+ --action-secret-border: 213 17% 35% / 0.7;
+
+ --action-tools: 14 50% 31%;
+ --action-tools-soft: 14 50% 31% / 0.16;
+ --action-tools-hover: 14 50% 31% / 0.30;
+ --action-tools-border: 14 50% 31% / 0.6;
+
+ --tint-soft: 16%;
+ --tint-border: 40%;
+}
+
+/* Body — weathered parchment */
+:root[data-theme="plague"] body {
+ background:
+ url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='300' height='300'><filter id='p'><feTurbulence baseFrequency='0.4' numOctaves='2'/><feColorMatrix values='0 0 0 0 0.50 0 0 0 0 0.40 0 0 0 0 0.25 0 0 0 0.18 0'/></filter><rect width='300' height='300' filter='url(%23p)'/></svg>"),
+ var(--bg-app);
+}
+
+:root[data-theme="plague"] ::selection {
+ background: rgba(120, 60, 40, 0.45);
+ color: #efeacf;
+}
diff --git a/client/src/themes/rot.css b/client/src/themes/rot.css
new file mode 100644
index 00000000..fc9030b1
--- /dev/null
+++ b/client/src/themes/rot.css
@@ -0,0 +1,134 @@
+/* ============================================================================
+ * themes/rot.css — moss-overgrown crypt lit by guttering candles.
+ *
+ * Bone whites, cold green, candleflame amber on charcoal. Reads like a
+ * grimoire. Ported from design_handoff_machinaos_themes/themes/rot.css.
+ * ============================================================================ */
+
+:root[data-theme="rot"] {
+ --bg-app: #14181a;
+ --bg-panel: #1c2226;
+ --bg-canvas: #0a0e10;
+ --bg-elevated: #242c30;
+ --bg-input: #0a0e10;
+ --bg-hover: rgba(120, 200, 120, 0.08);
+ --bg-active: rgba(120, 200, 120, 0.18);
+ --bg-overlay: rgba(0, 4, 6, 0.85);
+
+ --border-default: #2a3a30;
+ --border-strong: #4a6a4a;
+ --border-focus: #78c878;
+ --ornament-frame: none;
+
+ --fg-default: #c8d8c0;
+ --fg-muted: #788878;
+ --fg-faint: #485848;
+ --fg-on-accent: #0a0e10;
+ --fg-on-success: #0a0e10;
+ --fg-on-danger: #c8d8c0;
+ --fg-on-warning: #0a0e10;
+
+ --bone: #d8d0b8;
+ --candle: #e8a838;
+ --crypt: #4a3838;
+ --moss: #78c878;
+
+ --font-display: 'Pirata One', 'UnifrakturCook', serif;
+ --font-body: 'EB Garamond', 'Cormorant Garamond', serif;
+ --font-mono: 'JetBrains Mono', monospace;
+ --type-scale-base: 14px;
+ --type-tracking-display: 0.04em;
+ --type-uppercase: none;
+
+ --radius-sm: 1px;
+ --radius-md: 2px;
+ --radius-lg: 4px;
+ --radius-pill: 999px;
+
+ --dur-fast: 140ms;
+ --dur-default: 320ms;
+ --dur-slow: 680ms;
+ --ease-default: cubic-bezier(0.4, 0, 0.6, 1);
+ --ease-emphasis: cubic-bezier(0.4, 0, 0.6, 1);
+ --motion-style: drift;
+ --sound-pack: crypt;
+
+ --cursor-default: auto;
+ --cursor-pointer: pointer;
+ --scrollbar-track: #14181a;
+ --scrollbar-thumb: #4a6a4a;
+
+ /* Shadcn HSL bridge */
+ --background: 200 13% 9%;
+ --foreground: 90 22% 80%;
+ --card: 199 14% 17%;
+ --card-foreground: 90 22% 80%;
+ --popover: 199 14% 17%;
+ --popover-foreground: 90 22% 80%;
+
+ --primary: 120 43% 63%; /* moss bloom */
+ --primary-foreground: 200 25% 5%;
+ --secondary: 198 16% 13%;
+ --secondary-foreground: 90 22% 80%;
+ --muted: 198 16% 13%;
+ --muted-foreground: 120 6% 50%;
+ --accent: 35 78% 56%; /* candleflame amber */
+ --accent-foreground: 200 25% 5%;
+
+ --destructive: 0 49% 44%;
+ --destructive-foreground: 90 22% 80%;
+ --success: 120 43% 63%;
+ --warning: 35 78% 56%;
+ --info: 200 36% 53%;
+
+ --border: 145 16% 28%;
+ --input: 145 16% 28%;
+ --ring: 120 43% 63%;
+
+ /* Action role bridge */
+ --action-run: 120 43% 63%;
+ --action-run-soft: 120 43% 63% / 0.18;
+ --action-run-hover: 120 43% 63% / 0.32;
+ --action-run-border: 120 43% 63% / 0.7;
+
+ --action-stop: 0 49% 44%;
+ --action-stop-soft: 0 49% 44% / 0.20;
+ --action-stop-hover: 0 49% 44% / 0.34;
+ --action-stop-border: 0 49% 44% / 0.7;
+
+ --action-save: 35 78% 56%;
+ --action-save-soft: 35 78% 56% / 0.20;
+ --action-save-hover: 35 78% 56% / 0.34;
+ --action-save-border: 35 78% 56% / 0.7;
+
+ --action-config: 35 78% 56%;
+ --action-config-soft: 35 78% 56% / 0.18;
+ --action-config-hover: 35 78% 56% / 0.30;
+ --action-config-border: 35 78% 56% / 0.6;
+
+ --action-secret: 200 36% 53%;
+ --action-secret-soft: 200 36% 53% / 0.16;
+ --action-secret-hover: 200 36% 53% / 0.30;
+ --action-secret-border: 200 36% 53% / 0.6;
+
+ --action-tools: 120 43% 63%;
+ --action-tools-soft: 120 43% 63% / 0.16;
+ --action-tools-hover: 120 43% 63% / 0.30;
+ --action-tools-border: 120 43% 63% / 0.6;
+
+ --tint-soft: 16%;
+ --tint-border: 40%;
+}
+
+/* Body — moss + damp stone */
+:root[data-theme="rot"] body {
+ background:
+ radial-gradient(ellipse 80% 60% at 50% 0%, rgba(120,200,120,0.04), transparent 60%),
+ url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='300' height='300'><filter id='m'><feTurbulence baseFrequency='0.6' numOctaves='2'/><feColorMatrix values='0 0 0 0 0.05 0 0 0 0 0.10 0 0 0 0 0.05 0 0 0 0.4 0'/></filter><rect width='300' height='300' filter='url(%23m)'/></svg>"),
+ var(--bg-app);
+}
+
+:root[data-theme="rot"] ::selection {
+ background: rgba(120, 200, 120, 0.4);
+ color: #14181a;
+}
diff --git a/client/src/themes/steampunk.css b/client/src/themes/steampunk.css
new file mode 100644
index 00000000..1eb9e313
--- /dev/null
+++ b/client/src/themes/steampunk.css
@@ -0,0 +1,133 @@
+/* ============================================================================
+ * themes/steampunk.css — brass, copper, oiled leather, riveted plates.
+ *
+ * Reads like the inside of a Verne submarine.
+ * Ported from design_handoff_machinaos_themes/themes/steampunk.css.
+ * ============================================================================ */
+
+:root[data-theme="steampunk"] {
+ --bg-app: #2a1f12;
+ --bg-panel: #3a2a18;
+ --bg-canvas: #1a1208;
+ --bg-elevated: #4a3620;
+ --bg-input: #1a1208;
+ --bg-hover: rgba(200, 140, 40, 0.10);
+ --bg-active: rgba(200, 140, 40, 0.20);
+ --bg-overlay: rgba(20, 12, 6, 0.7);
+
+ --border-default: #6a4a20;
+ --border-strong: #b88838;
+ --border-focus: #d8a848;
+ --ornament-frame: none;
+
+ --fg-default: #e8d8b0;
+ --fg-muted: #b8a070;
+ --fg-faint: #786040;
+ --fg-on-accent: #2a1f12;
+ --fg-on-success: #2a1f12;
+ --fg-on-danger: #e8d8b0;
+ --fg-on-warning: #2a1f12;
+
+ --copper: #b8602a;
+ --rust: #8a3a1a;
+ --leather: #4a2818;
+ --brass: #d8a848;
+
+ --font-display: 'IM Fell English SC', 'Cinzel', serif;
+ --font-body: 'IM Fell English', 'EB Garamond', serif;
+ --font-mono: 'Special Elite', 'Courier Prime', monospace;
+ --type-scale-base: 14px;
+ --type-tracking-display: 0.10em;
+ --type-uppercase: uppercase;
+
+ --radius-sm: 2px;
+ --radius-md: 4px;
+ --radius-lg: 8px;
+ --radius-pill: 999px;
+
+ --dur-fast: 110ms;
+ --dur-default: 240ms;
+ --dur-slow: 480ms;
+ --ease-default: cubic-bezier(0.5, 0, 0.4, 1.1);
+ --ease-emphasis: cubic-bezier(0.7, -0.1, 0.3, 1.2);
+ --motion-style: mechanical;
+ --sound-pack: clockwork;
+
+ --cursor-default: auto;
+ --cursor-pointer: pointer;
+ --scrollbar-track: #2a1f12;
+ --scrollbar-thumb: #b88838;
+
+ /* Shadcn HSL bridge */
+ --background: 28 41% 12%;
+ --foreground: 40 53% 80%;
+ --card: 31 38% 21%;
+ --card-foreground: 40 53% 80%;
+ --popover: 31 38% 21%;
+ --popover-foreground: 40 53% 80%;
+
+ --primary: 40 64% 56%; /* brass */
+ --primary-foreground: 28 41% 12%;
+ --secondary: 30 39% 16%;
+ --secondary-foreground: 40 53% 80%;
+ --muted: 30 39% 16%;
+ --muted-foreground: 40 35% 58%;
+ --accent: 18 63% 44%; /* copper */
+ --accent-foreground: 28 41% 12%;
+
+ --destructive: 14 68% 32%; /* rust */
+ --destructive-foreground: 40 53% 80%;
+ --success: 79 41% 38%;
+ --warning: 40 64% 56%;
+ --info: 200 39% 47%;
+
+ --border: 33 53% 27%;
+ --input: 33 53% 27%;
+ --ring: 40 64% 56%;
+
+ /* Action role bridge */
+ --action-run: 79 41% 38%;
+ --action-run-soft: 79 41% 38% / 0.20;
+ --action-run-hover: 79 41% 38% / 0.34;
+ --action-run-border: 79 41% 38% / 0.7;
+
+ --action-stop: 14 68% 32%;
+ --action-stop-soft: 14 68% 32% / 0.20;
+ --action-stop-hover: 14 68% 32% / 0.34;
+ --action-stop-border: 14 68% 32% / 0.7;
+
+ --action-save: 40 64% 56%;
+ --action-save-soft: 40 64% 56% / 0.22;
+ --action-save-hover: 40 64% 56% / 0.36;
+ --action-save-border: 40 64% 56% / 0.7;
+
+ --action-config: 40 64% 56%;
+ --action-config-soft: 40 64% 56% / 0.18;
+ --action-config-hover: 40 64% 56% / 0.30;
+ --action-config-border: 40 64% 56% / 0.6;
+
+ --action-secret: 200 39% 47%;
+ --action-secret-soft: 200 39% 47% / 0.18;
+ --action-secret-hover: 200 39% 47% / 0.30;
+ --action-secret-border: 200 39% 47% / 0.6;
+
+ --action-tools: 18 63% 44%;
+ --action-tools-soft: 18 63% 44% / 0.20;
+ --action-tools-hover: 18 63% 44% / 0.34;
+ --action-tools-border: 18 63% 44% / 0.6;
+
+ --tint-soft: 16%;
+ --tint-border: 40%;
+}
+
+/* Body — riveted leather grain */
+:root[data-theme="steampunk"] body {
+ background:
+ url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='200' height='200'><filter id='l'><feTurbulence baseFrequency='0.8' numOctaves='2'/><feColorMatrix values='0 0 0 0 0.16 0 0 0 0 0.10 0 0 0 0 0.04 0 0 0 0.4 0'/></filter><rect width='200' height='200' filter='url(%23l)'/></svg>"),
+ var(--bg-app);
+}
+
+:root[data-theme="steampunk"] ::selection {
+ background: rgba(216, 168, 72, 0.5);
+ color: #2a1f12;
+}
diff --git a/client/src/themes/surveillance.css b/client/src/themes/surveillance.css
new file mode 100644
index 00000000..28ab9a8e
--- /dev/null
+++ b/client/src/themes/surveillance.css
@@ -0,0 +1,139 @@
+/* ============================================================================
+ * themes/surveillance.css — institutional grey, CCTV crosshair overlays.
+ *
+ * Bureaucratic, cold, all corners and IDs. Reads like a 1970s panopticon
+ * control room. Ported from
+ * design_handoff_machinaos_themes/themes/surveillance.css.
+ * ============================================================================ */
+
+:root[data-theme="surveillance"] {
+ --bg-app: #1a1c1e;
+ --bg-panel: #232628;
+ --bg-canvas: #0a0c0e;
+ --bg-elevated: #2c3034;
+ --bg-input: #0a0c0e;
+ --bg-hover: rgba(232, 38, 38, 0.08);
+ --bg-active: rgba(232, 38, 38, 0.18);
+ --bg-overlay: rgba(0, 0, 0, 0.85);
+
+ --border-default: #3a3e42;
+ --border-strong: #5a5e62;
+ --border-focus: #e82626;
+ --ornament-frame: none;
+
+ --fg-default: #c8ccd0;
+ --fg-muted: #888c90;
+ --fg-faint: #585c60;
+ --fg-on-accent: #ffffff;
+ --fg-on-success: #0a0c0e;
+ --fg-on-danger: #ffffff;
+ --fg-on-warning: #0a0c0e;
+
+ --phosphor: #6acc6a;
+ --amber: #d8a020;
+ --concrete: #888c90;
+ --rec-red: #e82626;
+
+ --font-display: 'Anonymous Pro', 'IBM Plex Mono', monospace;
+ --font-body: 'IBM Plex Mono', 'Anonymous Pro', monospace;
+ --font-mono: 'IBM Plex Mono', monospace;
+ --type-scale-base: 13px;
+ --type-tracking-display: 0.10em;
+ --type-uppercase: uppercase;
+
+ --radius-sm: 0px;
+ --radius-md: 0px;
+ --radius-lg: 0px;
+ --radius-pill: 0px;
+
+ --dur-fast: 60ms;
+ --dur-default: 140ms;
+ --dur-slow: 240ms;
+ --ease-default: linear;
+ --ease-emphasis: linear;
+ --motion-style: scanline;
+ --sound-pack: telex;
+
+ --cursor-default: auto;
+ --cursor-pointer: pointer;
+ --scrollbar-track: #1a1c1e;
+ --scrollbar-thumb: #5a5e62;
+
+ /* Shadcn HSL bridge */
+ --background: 210 6% 11%;
+ --foreground: 210 8% 80%;
+ --card: 210 7% 19%;
+ --card-foreground: 210 8% 80%;
+ --popover: 210 7% 19%;
+ --popover-foreground: 210 8% 80%;
+
+ --primary: 0 81% 53%; /* REC red */
+ --primary-foreground: 0 0% 100%;
+ --secondary: 210 6% 16%;
+ --secondary-foreground: 210 8% 80%;
+ --muted: 210 6% 16%;
+ --muted-foreground: 210 3% 56%;
+ --accent: 120 49% 61%; /* phosphor green */
+ --accent-foreground: 210 8% 5%;
+
+ --destructive: 0 81% 53%;
+ --destructive-foreground: 0 0% 100%;
+ --success: 120 49% 61%;
+ --warning: 41 74% 49%;
+ --info: 213 51% 56%;
+
+ --border: 213 5% 36%;
+ --input: 213 5% 36%;
+ --ring: 0 81% 53%;
+
+ /* Action role bridge */
+ --action-run: 120 49% 61%;
+ --action-run-soft: 120 49% 61% / 0.16;
+ --action-run-hover: 120 49% 61% / 0.30;
+ --action-run-border: 120 49% 61% / 0.7;
+
+ --action-stop: 0 81% 53%;
+ --action-stop-soft: 0 81% 53% / 0.18;
+ --action-stop-hover: 0 81% 53% / 0.32;
+ --action-stop-border: 0 81% 53% / 0.7;
+
+ --action-save: 120 49% 61%;
+ --action-save-soft: 120 49% 61% / 0.18;
+ --action-save-hover: 120 49% 61% / 0.32;
+ --action-save-border: 120 49% 61% / 0.7;
+
+ --action-config: 41 74% 49%;
+ --action-config-soft: 41 74% 49% / 0.16;
+ --action-config-hover: 41 74% 49% / 0.30;
+ --action-config-border: 41 74% 49% / 0.6;
+
+ --action-secret: 0 81% 53%;
+ --action-secret-soft: 0 81% 53% / 0.16;
+ --action-secret-hover: 0 81% 53% / 0.30;
+ --action-secret-border: 0 81% 53% / 0.6;
+
+ --action-tools: 213 51% 56%;
+ --action-tools-soft: 213 51% 56% / 0.16;
+ --action-tools-hover: 213 51% 56% / 0.30;
+ --action-tools-border: 213 51% 56% / 0.6;
+
+ --tint-soft: 16%;
+ --tint-border: 45%;
+}
+
+/* Body — monitor scanlines */
+:root[data-theme="surveillance"] body {
+ background:
+ repeating-linear-gradient(0deg, transparent 0, transparent 2px, rgba(0,0,0,0.18) 2px, rgba(0,0,0,0.18) 3px),
+ var(--bg-app);
+}
+
+:root[data-theme="surveillance"] ::selection {
+ background: rgba(232, 38, 38, 0.5);
+ color: #ffffff;
+}
+
+/* Phosphor scrollbars */
+:root[data-theme="surveillance"] ::-webkit-scrollbar-thumb {
+ background: #5a5e62;
+}
diff --git a/client/src/themes/wasteland.css b/client/src/themes/wasteland.css
new file mode 100644
index 00000000..ec0abe54
--- /dev/null
+++ b/client/src/themes/wasteland.css
@@ -0,0 +1,132 @@
+/* ============================================================================
+ * themes/wasteland.css — irradiated dust, rust, hand-painted warnings on
+ * scrap metal. Reads like a Mad Max settlement.
+ * Ported from design_handoff_machinaos_themes/themes/wasteland.css.
+ * ============================================================================ */
+
+:root[data-theme="wasteland"] {
+ --bg-app: #2a2018;
+ --bg-panel: #3a2c1c;
+ --bg-canvas: #1a1410;
+ --bg-elevated: #4a3826;
+ --bg-input: #1a1410;
+ --bg-hover: rgba(232, 140, 40, 0.10);
+ --bg-active: rgba(232, 140, 40, 0.22);
+ --bg-overlay: rgba(20, 12, 6, 0.78);
+
+ --border-default: #6a4a28;
+ --border-strong: #8a3a18;
+ --border-focus: #e88a28;
+ --ornament-frame: none;
+
+ --fg-default: #e8d8a8;
+ --fg-muted: #b89868;
+ --fg-faint: #786040;
+ --fg-on-accent: #1a1410;
+ --fg-on-success: #1a1410;
+ --fg-on-danger: #e8d8a8;
+ --fg-on-warning: #1a1410;
+
+ --rust: #8a3a18;
+ --bone: #d8c8a0;
+ --rad: #c8d038;
+ --ochre: #e88a28;
+
+ --font-display: 'Special Elite', 'Black Ops One', monospace;
+ --font-body: 'Special Elite', 'Courier Prime', monospace;
+ --font-mono: 'VT323', 'Courier New', monospace;
+ --type-scale-base: 14px;
+ --type-tracking-display: 0.10em;
+ --type-uppercase: uppercase;
+
+ --radius-sm: 0px;
+ --radius-md: 0px;
+ --radius-lg: 0px;
+ --radius-pill: 0px;
+
+ --dur-fast: 60ms;
+ --dur-default: 180ms;
+ --dur-slow: 320ms;
+ --ease-default: cubic-bezier(0.6, 0, 0.4, 1);
+ --ease-emphasis: cubic-bezier(0.6, 0, 0.4, 1);
+ --motion-style: jittery;
+ --sound-pack: scrap;
+
+ --cursor-default: auto;
+ --cursor-pointer: pointer;
+ --scrollbar-track: #2a2018;
+ --scrollbar-thumb: #8a3a18;
+
+ /* Shadcn HSL bridge */
+ --background: 30 28% 13%;
+ --foreground: 41 53% 78%;
+ --card: 28 32% 22%;
+ --card-foreground: 41 53% 78%;
+ --popover: 28 32% 22%;
+ --popover-foreground: 41 53% 78%;
+
+ --primary: 28 80% 53%; /* ochre */
+ --primary-foreground: 24 28% 8%;
+ --secondary: 28 36% 17%;
+ --secondary-foreground: 41 53% 78%;
+ --muted: 28 36% 17%;
+ --muted-foreground: 35 36% 56%;
+ --accent: 64 56% 51%; /* radioactive */
+ --accent-foreground: 24 28% 8%;
+
+ --destructive: 6 75% 41%;
+ --destructive-foreground: 41 53% 78%;
+ --success: 64 56% 41%;
+ --warning: 64 56% 51%;
+ --info: 28 80% 53%;
+
+ --border: 32 47% 28%;
+ --input: 32 47% 28%;
+ --ring: 28 80% 53%;
+
+ /* Action role bridge */
+ --action-run: 64 56% 41%;
+ --action-run-soft: 64 56% 41% / 0.20;
+ --action-run-hover: 64 56% 41% / 0.34;
+ --action-run-border: 64 56% 41% / 0.7;
+
+ --action-stop: 6 75% 41%;
+ --action-stop-soft: 6 75% 41% / 0.22;
+ --action-stop-hover: 6 75% 41% / 0.36;
+ --action-stop-border: 6 75% 41% / 0.7;
+
+ --action-save: 28 80% 53%;
+ --action-save-soft: 28 80% 53% / 0.20;
+ --action-save-hover: 28 80% 53% / 0.34;
+ --action-save-border: 28 80% 53% / 0.7;
+
+ --action-config: 64 56% 51%;
+ --action-config-soft: 64 56% 51% / 0.18;
+ --action-config-hover: 64 56% 51% / 0.32;
+ --action-config-border: 64 56% 51% / 0.6;
+
+ --action-secret: 28 80% 53%;
+ --action-secret-soft: 28 80% 53% / 0.16;
+ --action-secret-hover: 28 80% 53% / 0.30;
+ --action-secret-border: 28 80% 53% / 0.6;
+
+ --action-tools: 64 56% 51%;
+ --action-tools-soft: 64 56% 51% / 0.18;
+ --action-tools-hover: 64 56% 51% / 0.32;
+ --action-tools-border: 64 56% 51% / 0.6;
+
+ --tint-soft: 18%;
+ --tint-border: 45%;
+}
+
+/* Body — dust + grit texture */
+:root[data-theme="wasteland"] body {
+ background:
+ url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='300' height='300'><filter id='d'><feTurbulence baseFrequency='0.9' numOctaves='3'/><feColorMatrix values='0 0 0 0 0.55 0 0 0 0 0.40 0 0 0 0 0.18 0 0 0 0.16 0'/></filter><rect width='300' height='300' filter='url(%23d)'/></svg>"),
+ var(--bg-app);
+}
+
+:root[data-theme="wasteland"] ::selection {
+ background: rgba(232, 138, 40, 0.5);
+ color: #1a1410;
+}
diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.md
index 146a62c1..c7583e4b 100644
--- a/docs-internal/frontend_architecture.md
+++ b/docs-internal/frontend_architecture.md
@@ -162,9 +162,14 @@ client/src/
│ └── utils.ts # cn() = clsx + tailwind-merge (shadcn convention)
│
├── styles/
-│ └── theme.ts # LEGACY. Still exported for components that
-│ # reference theme.colors / theme.dracula.* directly.
-│ # Will shrink over time as those sites inline Tailwind tokens.
+│ └── theme.ts # `lightColors` / `darkColors` base packs +
+│ # `dracula` / `solarized` constants. Read
+│ # exclusively by `useAppTheme` (which
+│ # overlays per-theme accents on top of the
+│ # base pack — see hooks/useAppTheme.ts) and
+│ # by canvas node components for inline
+│ # gradients tied to per-definition node
+│ # colors. Not imported anywhere else.
│
├── services/
│ ├── executionService.ts # ExecutionResult shape + node-execution plumbing
@@ -184,7 +189,9 @@ client/src/
## Tokens + theming
-Single source of truth: [src/index.css](../client/src/index.css).
+The frontend ships **10 themes** organised utopian / dystopian: `light` · `dark` · `renaissance` · `greek` · `edo` · `steampunk` · `atomic` · `cyber` · `wasteland` · `rot` · `plague` · `surveillance`. Active theme is `<html data-theme="...">` set by `<ThemeProvider>` (see [contexts/ThemeContext.tsx](../client/src/contexts/ThemeContext.tsx)). Per-theme blocks live in [client/src/themes/](../client/src/themes/); shadcn-aliased HSL triplets in [src/index.css](../client/src/index.css). Full token contract, sound + decorative-layer wiring, and the 10-theme migration playbook in **[theme_system.md](./theme_system.md)** — read that before adding a theme or migrating a component.
+
+Single source of truth for the bridge: [src/index.css](../client/src/index.css).
```css
@import "tailwindcss";
@@ -222,6 +229,12 @@ Single source of truth: [src/index.css](../client/src/index.css).
--node-workflow: 27 100% 71%; /* + -soft / -border */
}
+/* Dark + the 8 designed themes each ship their own per-theme block.
+ * Every block redeclares the shadcn HSL triplets for the bridge AND
+ * the new-contract tokens (--bg-app, --fg-default, --font-display,
+ * --sound-pack, etc.) the migrated chrome consumes via Tailwind's
+ * --color-bg-app etc. utilities. See client/src/themes/<name>.css for
+ * the full 10-block set + theme_system.md for the contract. */
[data-theme="dark"] {
--background: 192 100% 11%; /* Solarized base03 */
--foreground: 60 30% 96%; /* Dracula fg */
@@ -246,15 +259,8 @@ Single source of truth: [src/index.css](../client/src/index.css).
Rules:
1. **HSL triplets, no `hsl()` wrapper.** Tailwind composes alpha via `bg-primary/50`.
2. **shadcn's variable names win** (`--background`, `--primary`, `--destructive`, etc.) so every shadcn-generated file resolves against our palette with no re-wiring.
-3. Dark mode flips via `[data-theme="dark"]` + Tailwind's `.dark` class, both set by `App.tsx`:
- ```tsx
- useEffect(() => {
- const root = document.documentElement;
- root.classList.toggle('dark', isDarkMode);
- root.dataset.theme = isDarkMode ? 'dark' : 'light';
- }, [isDarkMode]);
- ```
-4. `styles/theme.ts` (`theme.dracula.*`, `theme.colors.*`) is still exported for the canvas node components and `EdgeConditionEditor`. New code should prefer Tailwind classes (`bg-primary`, `bg-action-run-soft`, `bg-node-agent-soft`) or `hsl(var(--...))` inline. Palette names (`text-dracula-green`) are forbidden in components -- go through the matching `--action-X` or `--node-X` semantic role token.
+3. Theme switches via `[data-theme="<name>"]` set by `<ThemeProvider>`. Themes whose backgrounds are dark (`dark`, `cyber`, `wasteland`, `rot`, `surveillance`, `steampunk`) also flip Tailwind's `.dark` class so legacy `dark:` variants resolve correctly. The 10-way `THEME_OVERRIDES` map in [hooks/useAppTheme.ts](../client/src/hooks/useAppTheme.ts) layers per-theme accents (primary, focus, action colours, edge palette) on top of `lightColors` / `darkColors` for canvas surfaces.
+4. `styles/theme.ts` exports `lightColors` / `darkColors` base packs + raw `dracula` / `solarized` palette constants. Consumed only by `useAppTheme` (overlay merge) and canvas node components for inline per-definition gradients. New code uses Tailwind classes (`bg-primary`, `bg-action-run-soft`, `bg-node-agent-soft`, `bg-bg-app`, `text-fg-default`) or `hsl(var(--...))` inline. Palette names (`text-dracula-green`) are forbidden in components — go through the matching `--action-X` or `--node-X` semantic role token.
### Token tier — pick the most specific that fits
@@ -521,4 +527,6 @@ The `MACHINAOS_INSTALLING=true` env var suppresses the recursive project postins
This architecture is the post-migration state. Pre-migration was antd + `styled-components` + a custom theme.ts-driven palette. See [ui_migration_plan.md](./ui_migration_plan.md) for the phase-by-phase transition and the 17 commits that executed it.
-**`useAppTheme()` is grandfathered** for the canvas node components (`AIAgentNode`, `SquareNode`, `TriggerNode`, `StartNode`, `ToolkitNode`, `TeamMonitorNode`, `BaseChatModelNode`, `ModelNode`, `GenericNode`) and `EdgeConditionEditor` only — they interpolate per-definition `nodeColor` into gradients, borders, and React Flow `<Handle>` styles. Every other surface uses Tailwind + the token tiers above.
+**`useAppTheme()` powers the canvas + maps surface across all 10 themes.** The hook returns a `theme` object with the legacy `Colors` shape (`theme.colors.X`, `theme.isDarkMode`) so existing call sites don't change. Under non-light/dark themes it merges a per-theme overlay (primary, focus, action palette, edge stroke / selection / executing / completed / error) on top of the chosen base pack (`lightColors` for utopian-bright themes, `darkColors` for dystopian / dark themes). Adding a new theme overlay is a single entry in the `THEME_OVERRIDES` map in [hooks/useAppTheme.ts](../client/src/hooks/useAppTheme.ts).
+
+Read sites: every canvas node component (`AIAgentNode`, `SquareNode`, `TriggerNode`, `StartNode`, `ToolkitNode`, `TeamMonitorNode`, `GenericNode`), `EdgeConditionEditor`, and the Maps surface (`MapSelector`, `GoogleMapsPicker`, `MapsPreviewPanel`) — they interpolate per-definition `nodeColor` and JS-side hex values that Tailwind classes can't express. Every other surface uses Tailwind + the token tiers above and retints automatically through the per-theme `[data-theme="..."]` block.
diff --git a/docs-internal/theme_system.md b/docs-internal/theme_system.md
index 53b88709..9d374fa4 100644
--- a/docs-internal/theme_system.md
+++ b/docs-internal/theme_system.md
@@ -1,31 +1,51 @@
-# Theme System — design-handoff token contract + 4-way themes
+# Theme System — design-handoff token contract + 10 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.
+The MachinaOs frontend supports **ten visual themes**, organised as a utopian / dystopian taxonomy from the design handoff:
-This document is the playbook for working in the design system: token taxonomy, migration recipe, anti-patterns, and where each piece lives.
+**Utopian:** `light` · `dark` · `renaissance` · `greek` · `edo` · `steampunk` · `atomic`
+**Dystopian:** `cyber` · `wasteland` · `rot` · `plague` · `surveillance`
+
+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, motion, and sound-pack values.
+
+This document is the playbook for working in the design system: token taxonomy, decorative-layer wrappers, per-theme sound + canvas packs, 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
+├── base.css neutral defaults (space, radii, 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 + shadcn bridge
+├── greek.css :root[data-theme="greek"] — lapis + oxblood on marble
+├── edo.css :root[data-theme="edo"] — washi + sumi + vermillion
+├── steampunk.css :root[data-theme="steampunk"] — brass + copper on leather
+├── atomic.css :root[data-theme="atomic"] — atomic orange on cardstock
+├── cyber.css :root[data-theme="cyber"] — neon over void
+├── wasteland.css :root[data-theme="wasteland"] — ochre + radioactive scrap
+├── rot.css :root[data-theme="rot"] — moss bloom in crypt
+├── plague.css :root[data-theme="plague"] — woodcut quarantine
+└── surveillance.css :root[data-theme="surveillance"] — REC red + phosphor
client/src/index.css
-├── @layer base :root — shadcn HSL-triplet tokens (light defaults)
+├── @layer base :root — shadcn HSL-triplet tokens (light defaults) + dracula raw
├── @layer base .dark — shadcn HSL-triplet tokens (dark overrides)
└── @theme inline { … } — Tailwind v4 utility bindings for both contracts
+ (--color-bg-app, --color-fg-default, --color-border-default,
+ --font-display, --font-body, etc.)
client/src/contexts/ThemeContext.tsx
-├── theme: 'light' | 'dark' | 'renaissance' | 'cyber'
+├── ThemeName = 'light' | 'dark' | 'renaissance' | 'greek' | 'edo' | 'steampunk'
+│ | 'atomic' | 'cyber' | 'wasteland' | 'rot' | 'plague' | 'surveillance'
+├── DARK_FAMILY = {dark, cyber, wasteland, rot, surveillance, steampunk}
├── persists to localStorage['machinaos-theme']
-├── migrates legacy 'darkMode' boolean
-└── sets <html data-theme="..."> + (.dark class for legacy `dark:` Tailwind variants)
+├── migrates legacy 'darkMode' boolean on first load
+└── sets <html data-theme="..."> + .dark class (only for DARK_FAMILY themes)
-client/src/components/ui/ThemeSwitcher.tsx — DropdownMenu in TopToolbar
+client/src/hooks/useAppTheme.ts — 10-way Colors overlay (canvas + maps)
+client/src/lib/sound.ts — WebAudio engine, 10 packs × 9 events
+client/src/hooks/useSound.ts — useSoundSync() + useSound()
+client/src/components/ui/ThemeSwitcher.tsx — grouped DropdownMenu (System/Utopian/Dystopian)
client/src/components/ui/StatusBar.tsx — fixed-bottom system console
client/src/components/ui/CommandPalette.tsx + CommandPaletteHost.tsx — ⌘K launcher
```
@@ -58,9 +78,11 @@ Surface hierarchy across themes; every theme assigns these in its `:root[data-th
| 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) |
+| `border-border-default` | `--border-default` | Standard borders + dividers |
+| `border-border-strong` | `--border-strong` | Section separators, focused panels |
+| `border-border-focus` | `--border-focus` | Focus rings (often shadowed) |
+
+(Tailwind v4 names colour utilities `border-{token}` where `{token}` is the suffix after `--color-`; since we expose `--color-border-default`, the utility is `border-border-default`.)
| Tailwind utility | CSS var | Purpose |
|---|---|---|
@@ -118,7 +140,7 @@ Concrete swaps when migrating an existing component:
### Display-typography helper
-Heading surfaces under all four themes use the same triplet. Keep them grouped in the same className for clarity:
+Heading surfaces under all 10 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)]">
@@ -126,10 +148,18 @@ Heading surfaces under all four themes use the same triplet. Keep them grouped i
</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
+Result by theme (display font / tracking / case):
+- **Light + Dark** — Geist Variable / 0 / `none`
+- **Renaissance** — Cinzel / 0.10em / `uppercase`
+- **Greek** — Cinzel / 0.18em / `uppercase`
+- **Edo** — Shippori Mincho / 0.06em / `none`
+- **Steampunk** — IM Fell English SC / 0.10em / `uppercase`
+- **Atomic** — Bevan / 0.06em / `uppercase`
+- **Cyber** — Major Mono Display / 0.18em / `uppercase`
+- **Wasteland** — Special Elite / 0.10em / `uppercase`
+- **Rot** — Pirata One / 0.04em / `none`
+- **Plague** — UnifrakturCook / 0.06em / `uppercase`
+- **Surveillance** — Anonymous Pro / 0.10em / `uppercase`
## Adding a new theme
@@ -164,9 +194,12 @@ Result:
}
```
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.
+3. Add the name to `ThemeName` + `AVAILABLE_THEMES` in [client/src/contexts/ThemeContext.tsx](../client/src/contexts/ThemeContext.tsx). Add to `DARK_FAMILY` if the theme's background is dark.
+4. Add a `THEME_META` entry in [client/src/components/ui/ThemeSwitcher.tsx](../client/src/components/ui/ThemeSwitcher.tsx) (label + blurb) and append to the matching `THEME_GROUPS` row (System / Utopian / Dystopian).
+5. Add the theme name to `THEME_LABEL` in [client/src/components/ui/StatusBar.tsx](../client/src/components/ui/StatusBar.tsx) and [client/src/components/ui/CommandPaletteHost.tsx](../client/src/components/ui/CommandPaletteHost.tsx).
+6. **(Optional, canvas)** Add a `THEME_OVERRIDES` entry in [client/src/hooks/useAppTheme.ts](../client/src/hooks/useAppTheme.ts) so canvas selection rings, action buttons, and edge strokes pick up the theme's accents. Whichever keys you omit fall through to `lightColors` / `darkColors` (chosen by `DARK_BASE_THEMES`).
+7. **(Optional, fonts)** If the theme uses Google Fonts not already loaded, append the family to the deferred-load `<link>` in [client/index.html](../client/index.html).
+8. **(Optional, sound)** Pick one of the 10 existing `SoundPackName` values in `--sound-pack` (or add a new pack to [client/src/lib/sound.ts](../client/src/lib/sound.ts) and the `VALID_PACKS` set in [client/src/hooks/useSound.ts](../client/src/hooks/useSound.ts)).
**No component code changes.** That is the contract.
@@ -176,29 +209,76 @@ Result:
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.
+5. **`useAppTheme()` in new files.** Allowed only for surfaces that need JS-side hex values Tailwind can't express: canvas node components (`AIAgentNode`, `SquareNode`, `TriggerNode`, `StartNode`, `ToolkitNode`, `TeamMonitorNode`, `GenericNode`), `EdgeConditionEditor`, and the Google Maps SDK consumers (`MapSelector`, `GoogleMapsPicker`, `MapsPreviewPanel`). Every other surface uses Tailwind + tokens. New themes contribute to `useAppTheme` via a `THEME_OVERRIDES` entry, never by importing `lightColors` / `darkColors` directly.
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.
+8. **Static fallback theme palettes in TS.** Themes live in CSS (`client/src/themes/<name>.css`), not TS exports. `client/src/styles/theme.ts` ships only the two `lightColors` / `darkColors` base packs that `useAppTheme` overlays on top of — it is not a place to add a third / fourth / Nth palette.
## 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
+### Done
+- **Token contract**: all 10 themes ported in [client/src/themes/](../client/src/themes) (5 utopian + 5 dystopian)
+- **ThemeProvider** ([client/src/contexts/ThemeContext.tsx](../client/src/contexts/ThemeContext.tsx)) — 10-way `ThemeName`, `DARK_FAMILY` ⊃ `{dark, cyber, wasteland, rot, surveillance, steampunk}`, legacy `darkMode` localStorage migration on first load
+- **ThemeSwitcher** — DropdownMenu grouped into System / Utopian / Dystopian sections, all 10 themes
+- **Tailwind v4 `@theme inline`** exposing new-contract utilities (`bg-bg-app`, `text-fg-default`, `border-border-default`, `font-display`, `font-body`, `rounded-pill`)
+- **Decorative wrappers** — Dashboard root carries `app-frame`, the React Flow host carries `canvas-host`, every Modal carries `modal-frame`. Per-theme CSS targets these classes for outer ornaments (gilded corners, scanlines, riveted borders, REC dot, etc.)
+- **Migrated chrome**: TopToolbar, WorkflowSidebar, ComponentPalette + ComponentItem + CollapsibleSection, ConsolePanel chrome, SettingsPanel, Modal, ParameterPanel modal title, AIResultModal title, OutputDisplayPanel title, InputSection title
+- **New shell components**: StatusBar (fixed-bottom system line with WS connection / workflow / theme / clock), CommandPalette (`⌘K`), CommandPaletteHost (canonical command list with Workflow / Run / Open / View / Theme groups)
+- **Google Fonts** — deferred-load `<link>` covers all 10 themes' typefaces (Cinzel, Cormorant Garamond, IM Fell English / SC, JetBrains Mono, Major Mono Display, VT323, Shippori Mincho, Sawarabi Mincho, Special Elite, Bevan, Lato, Pirata One, EB Garamond, UnifrakturCook, Anonymous Pro, IBM Plex Mono, Courier Prime, Space Mono)
+- **Sound contract** — [client/src/lib/sound.ts](../client/src/lib/sound.ts) ports the upstream WebAudio engine with all 10 packs (`parchment`, `marble`, `ink`, `clockwork`, `vibraphone`, `terminal`, `scrap`, `crypt`, `bell`, `telex`). [client/src/hooks/useSound.ts](../client/src/hooks/useSound.ts) reads `--sound-pack` from `:root` on theme change and mirrors the `soundEnabled` Zustand slice into `Sounds.setEnabled()`. ActionButton fires `play('click')` from its onClick wrapper, Modal fires `play('modalOpen' | 'modalClose')` on the `isOpen` transition. Settings panel ships the toggle (Audio section). Persists to `localStorage['machinaos-sound']`; default off (opt-in).
+- **Canvas overlay packs** — [client/src/hooks/useAppTheme.ts](../client/src/hooks/useAppTheme.ts) extended from 2-way (`{light, dark}`) to 10-way: a `THEME_OVERRIDES` map applies a small overlay (primary, focus, focusRing, action colours, edge palette) on top of `lightColors` / `darkColors`. Existing call sites continue to read `theme.colors.X` and `theme.isDarkMode` unchanged; canvas selection rings, action buttons, and edge strokes pick up the active theme's accents under any of the 10 themes.
### 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.
+- **Per-theme icon sets** — the upstream [`app/icons.js`](../design_handoff_machinaos_themes/app/icons.js) ships 28-key glyph sets per theme (heraldic shields under Renaissance, wireframe + glow under Cyber, woodcut hatching under Plague, etc.). The current shell uses `lucide-react` icons under all themes via `currentColor`, which retints correctly via the bridge but doesn't carry per-theme glyph language. Migration recipe: build `client/src/icons/` with an `<Icon name>` component that reads the active theme via `useTheme()` and resolves to one of 10 SVG-string sets. Lucide stays as a fallback for missing keys.
+- **Per-component decorative class hooks** — the `.app-frame` / `.canvas-host` / `.modal-frame` wrappers are wired. A handful of finer-grained hooks remain (`.sq-node`, `.cat`, `.cmdk`, `.menu-pop`) — adding each to the matching React component is a one-line edit per surface and a no-op under themes that don't define decorations for it.
+- **Parameter panel internals** — `MiddleSection`, `MasterSkillEditor`, `ParameterRenderer` consume shadcn tokens through the bridge so they retint correctly, but their interior section headers don't yet carry the display-typography triplet. Apply the recipe (`font-display tracking-[var(--type-tracking-display)] text-fg-default [text-transform:var(--type-uppercase)]`) when next touched.
+- **Credentials modal sub-panels** — `OAuthPanel`, `EmailPanel`, `ApiKeyPanel`, `QrPairingPanel` headers same pattern.
+
+## Sound system
+
+Each theme declares `--sound-pack: "<pack>"` in its `:root[data-theme="..."]` block. Pack names map to event tables in [client/src/lib/sound.ts](../client/src/lib/sound.ts):
+
+| Theme | Pack | Voice |
+|---|---|---|
+| renaissance | `parchment` | Soft sine plucks + low-pass |
+| greek | `marble` | Warm chisel taps |
+| edo | `ink` | Soft brush + temple bell |
+| steampunk | `clockwork` | Mechanical ratchet + brass |
+| atomic | `vibraphone` | Mid-century jazz mallet |
+| cyber | `terminal` | Square-wave terminal beeps |
+| wasteland | `scrap` | Distorted clanging metal |
+| rot | `crypt` | Dripping water + low organ |
+| plague | `bell` | Struck church bell + stone echo |
+| surveillance | `telex` | Typewriter clack + Geiger tick |
+| light / dark | (system fallback `parchment`/`terminal` if requested) | — |
+
+Wiring:
+1. Mount `useSoundSync()` once at the Dashboard root — done in [client/src/Dashboard.tsx](../client/src/Dashboard.tsx).
+2. Every `<ActionButton>` fires `play('click')` on click via the CVA primitive — call sites don't need to wrap.
+3. `<Modal>` fires `play('modalOpen' | 'modalClose')` on `isOpen` edges.
+4. Settings panel ships an Audio section with a Switch bound to `useAppStore.soundEnabled`.
+
+Adding a new sound event: extend `SoundEvent` in `lib/sound.ts`, add an entry per pack, fire `play('<event>')` from the handler.
+
+## Canvas overlay packs (`useAppTheme`)
+
+The hook returns a `theme` object with the same shape every call site already destructures — `theme.colors.X` and `theme.isDarkMode` continue to work. Under non-light/dark themes a small overlay merges into the base pack:
+
+```typescript
+const THEME_OVERRIDES: Partial<Record<ThemeName, ColorOverride>> = {
+ cyber: {
+ primary: '#f51eb6', // neon magenta
+ focus: '#1dd9e5',
+ actionRun: '#26d97a',
+ edgeDefault: '#f51eb6',
+ edgeSelected: '#1dd9e5',
+ /* ... */
+ },
+ /* ... 9 more themes */
+};
+```
+
+The overlay only re-binds the keys most visible on the canvas (primary, focus, action buttons, edge palette). Everything else (background, text, border) stays on the chosen base pack (`darkColors` for `DARK_BASE_THEMES`, `lightColors` for the rest). Adding a new theme means adding one `THEME_OVERRIDES` entry; missing entries are a no-op (theme falls back to pure light/dark).
## Verification checklist
@@ -233,14 +313,26 @@ cd client && npx eslint <files>
| [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/themes/greek.css](../client/src/themes/greek.css) | Greek theme + bridge |
+| [client/src/themes/edo.css](../client/src/themes/edo.css) | Edo theme + bridge |
+| [client/src/themes/steampunk.css](../client/src/themes/steampunk.css) | Steampunk theme + bridge |
+| [client/src/themes/atomic.css](../client/src/themes/atomic.css) | Atomic Modern theme + bridge |
+| [client/src/themes/cyber.css](../client/src/themes/cyber.css) | Cyber-Tyranny theme + bridge |
+| [client/src/themes/wasteland.css](../client/src/themes/wasteland.css) | Wasteland theme + bridge |
+| [client/src/themes/rot.css](../client/src/themes/rot.css) | Necromantic Rot theme + bridge |
+| [client/src/themes/plague.css](../client/src/themes/plague.css) | Plague City theme + bridge |
+| [client/src/themes/surveillance.css](../client/src/themes/surveillance.css) | Surveillance 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/contexts/ThemeContext.tsx](../client/src/contexts/ThemeContext.tsx) | `<ThemeProvider>` + `useTheme()` (10-way) |
+| [client/src/hooks/useAppTheme.ts](../client/src/hooks/useAppTheme.ts) | Canvas overlay packs (10 themes × Colors override) |
+| [client/src/lib/sound.ts](../client/src/lib/sound.ts) | WebAudio engine — 10 sound packs, 9 events |
+| [client/src/hooks/useSound.ts](../client/src/hooks/useSound.ts) | `useSoundSync()` + `useSound()` React glue |
+| [client/src/components/ui/ThemeSwitcher.tsx](../client/src/components/ui/ThemeSwitcher.tsx) | Grouped dropdown picker (System / Utopian / Dystopian) |
| [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 |
+| [client/src/components/ui/action-button.tsx](../client/src/components/ui/action-button.tsx) | CVA action role primitive (fires `play('click')`) |
+| [client/src/components/ui/Modal.tsx](../client/src/components/ui/Modal.tsx) | Shared modal layout (fires `play('modalOpen'/'modalClose')`) |
+| [client/index.html](../client/index.html) | Google Fonts loading (all 10 themes' typefaces) |
| [design_handoff_machinaos_themes/](../design_handoff_machinaos_themes/) | Reference HTML mocks + token spec |
+| [design_handoff_machinaos_themes/MIGRATION_PLAYBOOK.md](../design_handoff_machinaos_themes/MIGRATION_PLAYBOOK.md) | Upstream recipe for the 4 deferred items (canvas, headers, decorative wrapper, sound) — all now landed |
diff --git a/docs-internal/ui_migration_plan.md b/docs-internal/ui_migration_plan.md
index f38a2d01..e4c3ee45 100644
--- a/docs-internal/ui_migration_plan.md
+++ b/docs-internal/ui_migration_plan.md
@@ -1,6 +1,6 @@
# Frontend UI Stack Migration — antd → shadcn/ui (canonical, no custom wrappers)
-> **Status (2026-04-14):** Phases 0–5 + 7 **complete**. Phase 6 (`ParameterRenderer` → JSON Forms) deferred pending backend `NodeSpec` handler. Zero antd / `@ant-design/icons` / styled-components imports remain. For the current state of the frontend see [frontend_architecture.md](./frontend_architecture.md) — that doc supersedes this plan as the source of truth for what the frontend IS; this doc documents how we got there.
+> **Status (2026-05-08):** Phases 0–5 + 7 **complete**. Phase 6 (`ParameterRenderer` → JSON Forms) deferred pending backend `NodeSpec` handler. Zero antd / `@ant-design/icons` / styled-components imports remain. Wave 12 retired the surviving tribal patterns (string-compares, opacity arithmetic, whole-store destructure). Wave 13 unified credential storage on a single source of truth + RFC 9700 / OWASP V9.9 compliance. **Wave 14** (May 2026) lit up the 10-theme design system end-to-end (chrome migration, decorative wrappers, sound packs, canvas overlays). Current state lives in [frontend_architecture.md](./frontend_architecture.md) and [theme_system.md](./theme_system.md) — those docs supersede this plan as the source of truth for what the frontend IS; this doc documents how we got there.
## Completion table
@@ -300,6 +300,39 @@ Driven by three sub-agent audits (broadcast asymmetry, duplicated caches, parall
- **`android_status` not invalidating catalogue** — separate handler bug; one-line follow-up.
- **`broadcastQueryClient` (TanStack Query experimental)**, Zod runtime validation at the WS boundary, event-id dedup `Set` for reconnect replay, AsyncAPI 3.0 spec, RFC 9700 single-use refresh-token rotation. Each becomes its own focused plan when justified.
+## Wave 14 — Theme system: 10 themes + decorative + sound + canvas overlays (May 2026)
+
+Driven by the upstream `design_handoff_machinaos_themes/` bundle expanding from 2 → 10 designed themes (5 utopian + 5 dystopian) and shipping a formal MIGRATION_PLAYBOOK for the four areas the prior pass deferred. Plan: [`.claude/plans/deploy-multiple-parallel-subagents-wild-turtle.md`](../../.claude/plans/deploy-multiple-parallel-subagents-wild-turtle.md). Two commits: `52c5229` (foundation: 4 themes + chrome migration + StatusBar + CommandPalette + playbook doc) and the subsequent push (Waves W1–W7 below). Full architecture lives in [theme_system.md](./theme_system.md) — that's the source of truth for the contract.
+
+| Wave | What it delivers | Where |
+|---|---|---|
+| W1 — 8 new themes ported | `client/src/themes/{greek,edo,steampunk,atomic,wasteland,rot,plague,surveillance}.css` ship the full new-contract token block (surface / fg / border / fonts / motion / sound-pack hint) + a shadcn HSL-triplet bridge so existing utilities (`bg-card`, `text-muted-foreground`, `<ActionButton>`) retint per theme. `ThemeContext` extends to 10-way `ThemeName` with `DARK_FAMILY ⊃ {dark, cyber, wasteland, rot, surveillance, steampunk}`. `ThemeSwitcher` regroups into System / Utopian / Dystopian dropdown sections; `StatusBar.THEME_LABEL` and `CommandPaletteHost.THEME_LABEL` records updated. | `client/src/themes/*.css`, `contexts/ThemeContext.tsx`, `components/ui/{ThemeSwitcher,StatusBar,CommandPaletteHost}.tsx`, `main.tsx` |
+| W2 — Decorative-layer wrappers | Dashboard root carries `app-frame`, the React Flow host carries `canvas-host`, every `<Modal>` carries `modal-frame`. Per-theme CSS targets these classes for outer ornaments (gilded corners on Renaissance, scanline overlay + corner brackets on Cyber, riveted ridged frame on Steampunk, REC dot on Surveillance, double-rule frame on Greek, nailed-up notice frame on Plague). All decorative pseudo-elements declare `pointer-events: none`. | `Dashboard.tsx`, `components/ui/Modal.tsx` |
+| W3 — Header-font migration | Modal title, Parameter Panel header, Input Section header, Output Display Panel header, AI Result Modal heading carry the display-typography triplet (`font-display tracking-[var(--type-tracking-display)] [text-transform:var(--type-uppercase)] text-fg-default`) so headers read as Cinzel / Major Mono / UnifrakturCook / etc. under the appropriate themes. Body copy stays on `--font-body`. | `ParameterPanel.tsx`, `parameterPanel/InputSection.tsx`, `ui/{Modal,OutputDisplayPanel,AIResultModal,SettingsPanel}.tsx`, `TopToolbar.tsx`, `WorkflowSidebar.tsx`, `ComponentPalette.tsx`, `ConsolePanel.tsx` |
+| W4 — Google Fonts | `client/index.html` deferred-loads 18 typefaces (Cinzel, Cormorant Garamond, IM Fell English / SC, JetBrains Mono, Major Mono Display, VT323, Shippori Mincho, Sawarabi Mincho, Special Elite, Bevan, Lato, Pirata One, EB Garamond, UnifrakturCook, Anonymous Pro, IBM Plex Mono, Courier Prime, Space Mono) covering all 10 themes' display + body + mono needs. `media="print" onload=this.media='all'` keeps the fetch off the critical path. | `client/index.html` |
+| W5 — Icon contract | **Deferred.** The upstream `app/icons.js` ships 28-key SVG glyph sets per theme (heraldic shields, wireframe glow, woodcut hatching, etc.). Lucide-react retints correctly via `currentColor` under all 10 themes via the bridge, so the contract is a polish item rather than a correctness fix. Migration recipe documented in `theme_system.md`. | (deferred) |
+| W6 — Sound contract | Full WebAudio engine ported from `app/sound.js` to `client/src/lib/sound.ts` — 10 packs (`parchment`, `marble`, `ink`, `clockwork`, `vibraphone`, `terminal`, `scrap`, `crypt`, `bell`, `telex`), 9 events (`click`, `hover`, `type`, `success`, `error`, `run`, `save`, `modalOpen`, `modalClose`), single shared `AudioContext` lazy-instantiated on first play. `client/src/hooks/useSound.ts` exposes `useSoundSync()` (mounts once at Dashboard root: mirrors `soundEnabled` slice into `Sounds.setEnabled`, reads `--sound-pack` from `:root` on every theme change, calls `Sounds.setPack(...)`) and `useSound()` (returns the play handle). `<ActionButton>`'s CVA primitive fires `play('click')` on every onClick — call sites unchanged. `<Modal>` fires `play('modalOpen' \| 'modalClose')` on `isOpen` edges via a previous-value ref. New `useAppStore.soundEnabled` slice (persisted to `localStorage['machinaos-sound']`, default off / opt-in) + Audio section in `SettingsPanel` with a `<Switch>` bound to it. | `lib/sound.ts`, `hooks/useSound.ts`, `store/useAppStore.ts`, `Dashboard.tsx`, `components/ui/{action-button,Modal,SettingsPanel}.tsx` |
+| W7 — Canvas overlay packs | `client/src/hooks/useAppTheme.ts` extended from 2-way (`{light, dark}`) to 10-way: `THEME_OVERRIDES: Partial<Record<ThemeName, ColorOverride>>` applies a small overlay (primary, focus, focusRing, action colours, edge palette) on top of `lightColors` / `darkColors`. Existing 23 `useAppTheme` call sites read `theme.colors.X` and `theme.isDarkMode` unchanged — the `Colors` shape is preserved. Canvas selection rings, action buttons, and edge strokes now pick up the active theme's accents under all 10 themes. The `ColorOverride = Partial<Record<keyof Colors, string>>` form widens `as const` literal types so themes can substitute arbitrary hex / rgba values. | `hooks/useAppTheme.ts` |
+
+**Wave 14 numbers:**
+- 8 new theme CSS files (~1500 LOC of bridged tokens + body textures + selection rules).
+- 10-way `ThemeContext` + `ThemeSwitcher` (System / Utopian / Dystopian groups) + `StatusBar` + `CommandPaletteHost`.
+- 1 new sound engine (`lib/sound.ts`, ~250 LOC) + 1 new hook (`useSound.ts`, ~50 LOC).
+- 10-way `useAppTheme` overlay map (~150 LOC).
+- 18 Google Fonts wired via single `<link>` deferred load.
+- `tsgo --noEmit` clean. `vite build` clean (14s, 145 KB CSS / 796 KB main bundle). 0 lint errors; 8 pre-existing convention warnings.
+
+**Architectural delta (permanent):**
+- Theme switching is purely CSS-variable-driven. Components render against `var(--token)` references only — no theme-conditional logic in component bodies. Adding a new theme = drop a CSS file in `client/src/themes/`, import in `main.tsx`, add to `AVAILABLE_THEMES`. Optional: `THEME_META` blurb, `THEME_OVERRIDES` canvas pack, `THEME_LABEL` in `StatusBar` / `CommandPaletteHost`. No component changes.
+- `useAppTheme` is now the single canvas + maps theme accessor across all 10 themes. The overlay form preserves the existing `Colors` shape so call sites don't migrate; new themes just contribute an overlay entry.
+- Per-theme sound packs ride a single `--sound-pack` CSS token. JS reads it on theme change via `getComputedStyle`; no component-level pack wiring.
+- Decorative ornaments live entirely in per-theme CSS targeting `.app-frame` / `.canvas-host` / `.modal-frame` wrappers. Adding new ornaments is per-theme CSS only.
+
+**Out of scope (deferred, with rationale):**
+- **Per-theme icon SVG sets** — `app/icons.js` ships 28-key glyph sets per theme. Lucide-react via `currentColor` is functionally correct under all themes; per-theme glyph language (heraldic shields, wireframe glow, woodcut hatching) is a polish layer to add when the UX team agrees it's worth the SVG payload.
+- **Per-component decorative class hooks** beyond `app-frame` / `canvas-host` / `modal-frame` — `.sq-node`, `.cat`, `.cmdk`, `.menu-pop` add finer-grained per-theme decorations. Each is a one-line className edit; ship as themes ship.
+- **Deeper Parameter Panel + Credentials sub-panel header migration** — body copy + form labels retint via the bridge but interior section headers (`MiddleSection` group labels, `MasterSkillEditor` split-panel heads, `ApiKeyPanel` / `OAuthPanel` / `EmailPanel` / `QrPairingPanel` section titles) don't yet carry the display-typography triplet. Apply the recipe (`font-display tracking-[var(--type-tracking-display)] text-fg-default [text-transform:var(--type-uppercase)]`) when those files are next touched.
+
## Context
The MachinaOs frontend was coupled to Ant Design (40 files, 187-line theme file, `ConfigProvider` at root). Pre-migration audit + research docs (now deleted; see git history under commit `4cb3dd9` if needed) prescribed shadcn/ui (canonical components copied via CLI registry) + Radix primitives + Tailwind 4 + JSON Forms for a schema-driven inspector. Phase 0/1 commits (`2209dba`, `7ac69fe`) included hand-written primitives and a toast facade — those got deleted as part of corrected Phase 0 (`cdeebb4`).