From 753d8658919d79f73693104bf32be00907934346 Mon Sep 17 00:00:00 2001
From: Haoqing Wang <haoqing@users.noreply.github.com>
Date: Sat, 18 Apr 2026 12:19:00 +0800
Subject: [PATCH 1/2] feat(ui): add IconButton + Tooltip primitives and
 feedback tokens

- IconButton: compact square button for toolbar/topbar use, with focus
  ring and disabled state aligned to existing Button.
- Tooltip: pure-CSS tooltip with 400ms hover delay (no JS, no Radix).
- Tokens: add --color-toast-success, --color-toast-error, --color-overlay
  for both light and dark palettes.

Tier 1 only: no Radix, no animation libs.

Signed-off-by: Haoqing Wang <haoqing@users.noreply.github.com>
---
 packages/ui/src/components/IconButton.tsx | 31 +++++++++++++++++++++++
 packages/ui/src/components/Tooltip.tsx    | 26 +++++++++++++++++++
 packages/ui/src/index.ts                  |  4 +++
 packages/ui/src/tokens.css                |  9 +++++++
 4 files changed, 70 insertions(+)
 create mode 100644 packages/ui/src/components/IconButton.tsx
 create mode 100644 packages/ui/src/components/Tooltip.tsx

diff --git a/packages/ui/src/components/IconButton.tsx b/packages/ui/src/components/IconButton.tsx
new file mode 100644
index 00000000..db927c17
--- /dev/null
+++ b/packages/ui/src/components/IconButton.tsx
@@ -0,0 +1,31 @@
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+
+export interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  size?: 'sm' | 'md';
+  label: string;
+  children: ReactNode;
+}
+
+const sizeClass: Record<NonNullable<IconButtonProps['size']>, string> = {
+  sm: 'h-7 w-7',
+  md: 'h-9 w-9',
+};
+
+export function IconButton({
+  size = 'md',
+  label,
+  className = '',
+  children,
+  ...rest
+}: IconButtonProps) {
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      className={`inline-flex items-center justify-center rounded-[var(--radius-md)] text-[var(--color-text-secondary)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-surface-hover)] transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-accent)] disabled:opacity-50 disabled:pointer-events-none ${sizeClass[size]} ${className}`}
+      {...rest}
+    >
+      {children}
+    </button>
+  );
+}
diff --git a/packages/ui/src/components/Tooltip.tsx b/packages/ui/src/components/Tooltip.tsx
new file mode 100644
index 00000000..ce5823b3
--- /dev/null
+++ b/packages/ui/src/components/Tooltip.tsx
@@ -0,0 +1,26 @@
+import type { ReactNode } from 'react';
+
+export interface TooltipProps {
+  label: string;
+  side?: 'top' | 'bottom';
+  children: ReactNode;
+}
+
+const sideClass: Record<NonNullable<TooltipProps['side']>, string> = {
+  top: 'bottom-full mb-1.5 left-1/2 -translate-x-1/2',
+  bottom: 'top-full mt-1.5 left-1/2 -translate-x-1/2',
+};
+
+export function Tooltip({ label, side = 'bottom', children }: TooltipProps) {
+  return (
+    <span className="relative inline-flex group">
+      {children}
+      <span
+        role="tooltip"
+        className={`pointer-events-none absolute ${sideClass[side]} z-50 whitespace-nowrap rounded-[var(--radius-sm)] bg-[var(--color-text-primary)] px-2 py-1 text-xs font-medium text-[var(--color-background)] opacity-0 transition-opacity duration-150 delay-[400ms] group-hover:opacity-100 group-focus-within:opacity-100 shadow-[var(--shadow-card)]`}
+      >
+        {label}
+      </span>
+    </span>
+  );
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 7be7a34f..999faab6 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -1,4 +1,8 @@
 export { Button } from './components/Button';
 export { Card } from './components/Card';
+export { IconButton } from './components/IconButton';
+export { Tooltip } from './components/Tooltip';
 export type { ButtonProps } from './components/Button';
 export type { CardProps } from './components/Card';
+export type { IconButtonProps } from './components/IconButton';
+export type { TooltipProps } from './components/Tooltip';
diff --git a/packages/ui/src/tokens.css b/packages/ui/src/tokens.css
index 2e3714cd..c2509d6a 100644
--- a/packages/ui/src/tokens.css
+++ b/packages/ui/src/tokens.css
@@ -34,6 +34,11 @@
   --color-error: #b04030;
   --color-mcp: #4a6b8a;
 
+  /* Feedback */
+  --color-toast-success: #4f7a52;
+  --color-toast-error: #b04030;
+  --color-overlay: rgba(31, 29, 24, 0.45);
+
   /* Shadow */
   --shadow-soft: 0 1px 2px rgba(31, 29, 24, 0.04);
   --shadow-card: 0 2px 8px rgba(31, 29, 24, 0.06);
@@ -76,6 +81,10 @@
   --color-error: #d96050;
   --color-mcp: #6a8aab;
 
+  --color-toast-success: #6b9c6e;
+  --color-toast-error: #d96050;
+  --color-overlay: rgba(0, 0, 0, 0.6);
+
   --shadow-soft: 0 1px 2px rgba(0, 0, 0, 0.3);
   --shadow-card: 0 2px 8px rgba(0, 0, 0, 0.4);
   --shadow-elevated: 0 8px 24px rgba(0, 0, 0, 0.5);

From 7f3bd6afea502fd06ea08c28678dbcca5e4bcd34 Mon Sep 17 00:00:00 2001
From: Haoqing Wang <haoqing@users.noreply.github.com>
Date: Sat, 18 Apr 2026 12:19:17 +0800
Subject: [PATCH 2/2] feat(desktop): settings + theme + command palette +
 better preview states

Reshape the renderer so the app feels like a real product even before any
AI call succeeds. All Tier 1, no new prod deps.

Added:
- TopBar with breadcrumb + 3 icon-buttons (palette / theme / settings),
  using the macOS hiddenInset drag region.
- Settings overlay with 4 tabs: Models (stub), Appearance (theme picker),
  Storage (config file path), Advanced (placeholder).
- CommandPalette overlay (Cmd+K) with 4 actions: New Design, Toggle
  Theme, Open Settings, Export (stub).
- ThemeToggle: persists to localStorage; index.html bootstraps the
  `.dark` class inline before React mounts to avoid FOUC.
- ToastViewport (Zustand-backed, auto-dismiss 4s, stack bottom-right)
  surfacing generation success and errors.
- PreviewPane with three explicit states: EmptyState (chips populate
  the prompt input), LoadingState (CSS shimmer), ErrorState (Retry +
  Copy Error card).
- useKeyboard hook: central keymap registry on plain addEventListener.
  Cmd+Enter sends, Cmd+, opens Settings, Cmd+K opens palette, Esc
  closes overlays.
- Sidebar extracted from App.tsx; App.tsx is now a slim composition.

Store gains: theme, settingsOpen, commandPaletteOpen, toasts, lastError,
plus retryLastPrompt + clearError.

No silent fallbacks: every error path pushes a toast and surfaces in
ErrorState. All UI uses var(--color-*) tokens; no hex literals; no new
hardcoded px sizes added.

Signed-off-by: Haoqing Wang <haoqing@users.noreply.github.com>
---
 apps/desktop/src/renderer/index.html          |  10 +
 apps/desktop/src/renderer/src/App.tsx         | 191 +++++++-----------
 .../src/components/CommandPalette.tsx         | 175 ++++++++++++++++
 .../renderer/src/components/PreviewPane.tsx   |  48 +++++
 .../src/renderer/src/components/Settings.tsx  | 168 +++++++++++++++
 .../src/renderer/src/components/Sidebar.tsx   |  68 +++++++
 .../renderer/src/components/ThemeToggle.tsx   |  16 ++
 .../src/renderer/src/components/Toast.tsx     |  64 ++++++
 .../src/renderer/src/components/TopBar.tsx    |  53 +++++
 .../src/renderer/src/hooks/useKeyboard.ts     |  45 +++++
 apps/desktop/src/renderer/src/index.css       |  51 +++++
 .../src/renderer/src/preview/EmptyState.tsx   |  56 +++++
 .../src/renderer/src/preview/ErrorState.tsx   |  57 ++++++
 .../src/renderer/src/preview/LoadingState.tsx |  22 ++
 apps/desktop/src/renderer/src/store.ts        | 122 ++++++++++-
 15 files changed, 1025 insertions(+), 121 deletions(-)
 create mode 100644 apps/desktop/src/renderer/src/components/CommandPalette.tsx
 create mode 100644 apps/desktop/src/renderer/src/components/PreviewPane.tsx
 create mode 100644 apps/desktop/src/renderer/src/components/Settings.tsx
 create mode 100644 apps/desktop/src/renderer/src/components/Sidebar.tsx
 create mode 100644 apps/desktop/src/renderer/src/components/ThemeToggle.tsx
 create mode 100644 apps/desktop/src/renderer/src/components/Toast.tsx
 create mode 100644 apps/desktop/src/renderer/src/components/TopBar.tsx
 create mode 100644 apps/desktop/src/renderer/src/hooks/useKeyboard.ts
 create mode 100644 apps/desktop/src/renderer/src/preview/EmptyState.tsx
 create mode 100644 apps/desktop/src/renderer/src/preview/ErrorState.tsx
 create mode 100644 apps/desktop/src/renderer/src/preview/LoadingState.tsx

diff --git a/apps/desktop/src/renderer/index.html b/apps/desktop/src/renderer/index.html
index 61e7933a..9c339e8c 100644
--- a/apps/desktop/src/renderer/index.html
+++ b/apps/desktop/src/renderer/index.html
@@ -14,6 +14,16 @@
   </head>
   <body>
     <div id="root"></div>
+    <script>
+      (function () {
+        try {
+          var t = localStorage.getItem('open-codesign:theme');
+          if (t === 'dark') document.documentElement.classList.add('dark');
+        } catch (e) {
+          /* localStorage unavailable; default light theme */
+        }
+      })();
+    </script>
     <script type="module" src="./src/main.tsx"></script>
   </body>
 </html>
diff --git a/apps/desktop/src/renderer/src/App.tsx b/apps/desktop/src/renderer/src/App.tsx
index e761430c..e0ef2917 100644
--- a/apps/desktop/src/renderer/src/App.tsx
+++ b/apps/desktop/src/renderer/src/App.tsx
@@ -1,131 +1,86 @@
-import { buildSrcdoc } from '@open-codesign/runtime';
-import { BUILTIN_DEMOS } from '@open-codesign/templates';
-import { Button } from '@open-codesign/ui';
-import { Send, Sparkles } from 'lucide-react';
-import { useState } from 'react';
+import { useMemo, useState } from 'react';
+import { CommandPalette } from './components/CommandPalette';
+import { PreviewPane } from './components/PreviewPane';
+import { Settings } from './components/Settings';
+import { Sidebar } from './components/Sidebar';
+import { ToastViewport } from './components/Toast';
+import { TopBar } from './components/TopBar';
+import { useKeyboard } from './hooks/useKeyboard';
 import { useCodesignStore } from './store';
 
 export function App() {
-  const messages = useCodesignStore((s) => s.messages);
-  const previewHtml = useCodesignStore((s) => s.previewHtml);
-  const isGenerating = useCodesignStore((s) => s.isGenerating);
   const sendPrompt = useCodesignStore((s) => s.sendPrompt);
+  const isGenerating = useCodesignStore((s) => s.isGenerating);
+  const openSettings = useCodesignStore((s) => s.openSettings);
+  const closeSettings = useCodesignStore((s) => s.closeSettings);
+  const openCommandPalette = useCodesignStore((s) => s.openCommandPalette);
+  const closeCommandPalette = useCodesignStore((s) => s.closeCommandPalette);
+  const settingsOpen = useCodesignStore((s) => s.settingsOpen);
+  const commandPaletteOpen = useCodesignStore((s) => s.commandPaletteOpen);
+
   const [prompt, setPrompt] = useState('');
 
-  function handleSubmit(e: React.FormEvent) {
-    e.preventDefault();
-    if (!prompt.trim() || isGenerating) return;
-    void sendPrompt(prompt);
+  function submit() {
+    const trimmed = prompt.trim();
+    if (!trimmed || isGenerating) return;
+    void sendPrompt(trimmed);
     setPrompt('');
   }
 
-  return (
-    <div className="h-full grid grid-cols-[380px_1fr] bg-[var(--color-background)]">
-      <aside className="flex flex-col border-r border-[var(--color-border)] bg-[var(--color-background-secondary)]">
-        <header className="px-5 py-4 border-b border-[var(--color-border)]">
-          <div className="flex items-center gap-2">
-            <Sparkles className="w-5 h-5 text-[var(--color-accent)]" />
-            <span className="font-semibold text-[var(--color-text-primary)]">open-codesign</span>
-            <span className="ml-auto text-xs text-[var(--color-text-muted)]">pre-alpha</span>
-          </div>
-        </header>
-
-        <div className="flex-1 overflow-y-auto px-5 py-4 space-y-4">
-          {messages.length === 0 ? (
-            <div>
-              <p className="text-sm text-[var(--color-text-secondary)] mb-3">
-                Try a starter prompt:
-              </p>
-              <ul className="space-y-2">
-                {BUILTIN_DEMOS.map((demo) => (
-                  <li key={demo.id}>
-                    <button
-                      type="button"
-                      onClick={() => setPrompt(demo.prompt)}
-                      className="w-full text-left px-3 py-2 rounded-[var(--radius-md)] bg-[var(--color-surface)] border border-[var(--color-border)] hover:bg-[var(--color-surface-hover)] transition-colors"
-                    >
-                      <div className="text-sm font-medium text-[var(--color-text-primary)]">
-                        {demo.title}
-                      </div>
-                      <div className="text-xs text-[var(--color-text-muted)] mt-0.5">
-                        {demo.description}
-                      </div>
-                    </button>
-                  </li>
-                ))}
-              </ul>
-            </div>
-          ) : (
-            messages.map((m, i) => (
-              <div
-                // biome-ignore lint/suspicious/noArrayIndexKey: tier-1 chat list with no reordering
-                key={`${m.role}-${i}`}
-                className={`px-3 py-2 rounded-[var(--radius-md)] text-sm ${
-                  m.role === 'user'
-                    ? 'bg-[var(--color-accent-muted)] text-[var(--color-text-primary)]'
-                    : 'bg-[var(--color-surface)] border border-[var(--color-border)] text-[var(--color-text-primary)]'
-                }`}
-              >
-                {m.content}
-              </div>
-            ))
-          )}
-        </div>
-
-        <form
-          onSubmit={handleSubmit}
-          className="border-t border-[var(--color-border)] p-3 flex gap-2"
-        >
-          <input
-            type="text"
-            value={prompt}
-            onChange={(e) => setPrompt(e.target.value)}
-            placeholder="Describe what to design…"
-            disabled={isGenerating}
-            className="flex-1 px-3 py-2 rounded-[var(--radius-md)] bg-[var(--color-surface)] border border-[var(--color-border)] text-sm text-[var(--color-text-primary)] placeholder:text-[var(--color-text-muted)] focus:outline-none focus:border-[var(--color-accent)]"
-          />
-          <Button type="submit" size="md" disabled={isGenerating || !prompt.trim()}>
-            <Send className="w-4 h-4" />
-          </Button>
-        </form>
-      </aside>
+  const bindings = useMemo(
+    () => [
+      {
+        combo: 'mod+enter',
+        handler: () => {
+          const trimmed = prompt.trim();
+          if (!trimmed || isGenerating) return;
+          void sendPrompt(trimmed);
+          setPrompt('');
+        },
+      },
+      {
+        combo: 'mod+,',
+        handler: () => openSettings(),
+      },
+      {
+        combo: 'mod+k',
+        handler: () => openCommandPalette(),
+      },
+      {
+        combo: 'escape',
+        handler: () => {
+          if (settingsOpen) closeSettings();
+          else if (commandPaletteOpen) closeCommandPalette();
+        },
+        preventDefault: false,
+      },
+    ],
+    [
+      prompt,
+      isGenerating,
+      sendPrompt,
+      settingsOpen,
+      commandPaletteOpen,
+      openSettings,
+      openCommandPalette,
+      closeSettings,
+      closeCommandPalette,
+    ],
+  );
+  useKeyboard(bindings);
 
-      <main className="flex flex-col">
-        <header className="h-12 px-5 border-b border-[var(--color-border)] flex items-center justify-between">
-          <span className="text-sm text-[var(--color-text-secondary)]">
-            {previewHtml ? 'Preview' : 'No design yet'}
-          </span>
-          <span className="text-xs text-[var(--color-text-muted)]">
-            BYOK · local-first · multi-model
-          </span>
-        </header>
-        <div className="flex-1 p-6 overflow-auto">
-          {previewHtml ? (
-            <iframe
-              key={previewHtml.length}
-              title="design-preview"
-              sandbox="allow-scripts"
-              srcDoc={buildSrcdoc(previewHtml)}
-              className="w-full h-full bg-white rounded-[var(--radius-2xl)] shadow-[var(--shadow-card)] border border-[var(--color-border)]"
-            />
-          ) : (
-            <div className="h-full flex items-center justify-center">
-              <div className="text-center max-w-md">
-                <div className="w-16 h-16 mx-auto mb-4 rounded-full bg-[var(--color-surface)] border border-[var(--color-border)] flex items-center justify-center">
-                  <Sparkles className="w-7 h-7 text-[var(--color-accent)]" />
-                </div>
-                <h2 className="text-lg font-semibold text-[var(--color-text-primary)] mb-2">
-                  Design with AI
-                </h2>
-                <p className="text-sm text-[var(--color-text-secondary)]">
-                  Pick a starter on the left, or describe what you want to design. The result
-                  renders here in a sandboxed preview.
-                </p>
-              </div>
-            </div>
-          )}
-        </div>
-      </main>
+  return (
+    <div className="h-full flex flex-col bg-[var(--color-background)]">
+      <TopBar />
+      <div className="flex-1 grid grid-cols-[380px_1fr] min-h-0">
+        <Sidebar prompt={prompt} setPrompt={setPrompt} onSubmit={submit} />
+        <main className="flex flex-col min-h-0">
+          <PreviewPane onPickStarter={(p) => setPrompt(p)} />
+        </main>
+      </div>
+      <Settings />
+      <CommandPalette />
+      <ToastViewport />
     </div>
   );
 }
diff --git a/apps/desktop/src/renderer/src/components/CommandPalette.tsx b/apps/desktop/src/renderer/src/components/CommandPalette.tsx
new file mode 100644
index 00000000..2bc56042
--- /dev/null
+++ b/apps/desktop/src/renderer/src/components/CommandPalette.tsx
@@ -0,0 +1,175 @@
+import { Download, Moon, Plus, Settings as SettingsIcon } from 'lucide-react';
+import { useEffect, useMemo, useState } from 'react';
+import { useCodesignStore } from '../store';
+
+interface PaletteAction {
+  id: string;
+  label: string;
+  hint: string;
+  icon: typeof Plus;
+  run: () => void;
+}
+
+export function CommandPalette() {
+  const open = useCodesignStore((s) => s.commandPaletteOpen);
+  const close = useCodesignStore((s) => s.closeCommandPalette);
+  const openSettings = useCodesignStore((s) => s.openSettings);
+  const toggleTheme = useCodesignStore((s) => s.toggleTheme);
+  const pushToast = useCodesignStore((s) => s.pushToast);
+
+  const [query, setQuery] = useState('');
+  const [cursor, setCursor] = useState(0);
+
+  const actions: PaletteAction[] = useMemo(
+    () => [
+      {
+        id: 'new-design',
+        label: 'New Design',
+        hint: 'Clear chat and start fresh',
+        icon: Plus,
+        run: () => {
+          useCodesignStore.setState({
+            messages: [],
+            previewHtml: null,
+            errorMessage: null,
+          });
+          pushToast({ variant: 'info', title: 'Workspace cleared' });
+        },
+      },
+      {
+        id: 'toggle-theme',
+        label: 'Toggle Theme',
+        hint: 'Switch between light and dark',
+        icon: Moon,
+        run: toggleTheme,
+      },
+      {
+        id: 'open-settings',
+        label: 'Open Settings',
+        hint: 'Models, appearance, storage',
+        icon: SettingsIcon,
+        run: openSettings,
+      },
+      {
+        id: 'export',
+        label: 'Export',
+        hint: 'Coming soon',
+        icon: Download,
+        run: () =>
+          pushToast({
+            variant: 'info',
+            title: 'Export not available yet',
+            description: 'PDF and PPTX exporters land in v0.2.',
+          }),
+      },
+    ],
+    [openSettings, toggleTheme, pushToast],
+  );
+
+  const filtered = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    if (!q) return actions;
+    return actions.filter(
+      (a) => a.label.toLowerCase().includes(q) || a.hint.toLowerCase().includes(q),
+    );
+  }, [actions, query]);
+
+  useEffect(() => {
+    if (!open) {
+      setQuery('');
+      setCursor(0);
+    }
+  }, [open]);
+
+  useEffect(() => {
+    if (cursor >= filtered.length) setCursor(0);
+  }, [cursor, filtered.length]);
+
+  if (!open) return null;
+
+  function runAt(i: number) {
+    const action = filtered[i];
+    if (!action) return;
+    action.run();
+    close();
+  }
+
+  return (
+    <div
+      // biome-ignore lint/a11y/useSemanticElements: native <dialog> top-layer rendering interferes with our overlay stack
+      role="dialog"
+      aria-modal="true"
+      aria-label="Command palette"
+      className="fixed inset-0 z-50 flex items-start justify-center pt-24 px-6 bg-[var(--color-overlay)] animate-[overlay-in_120ms_ease-out]"
+      onClick={close}
+      onKeyDown={(e) => {
+        if (e.key === 'Escape') close();
+      }}
+    >
+      <div
+        className="w-full max-w-lg rounded-[var(--radius-2xl)] bg-[var(--color-background)] border border-[var(--color-border)] shadow-[var(--shadow-elevated)] overflow-hidden animate-[panel-in_160ms_ease-out]"
+        onClick={(e) => e.stopPropagation()}
+        onKeyDown={(e) => {
+          if (e.key === 'ArrowDown') {
+            e.preventDefault();
+            setCursor((c) => Math.min(c + 1, filtered.length - 1));
+          } else if (e.key === 'ArrowUp') {
+            e.preventDefault();
+            setCursor((c) => Math.max(c - 1, 0));
+          } else if (e.key === 'Enter') {
+            e.preventDefault();
+            runAt(cursor);
+          } else if (e.key === 'Escape') {
+            close();
+          }
+        }}
+        role="document"
+      >
+        <input
+          // biome-ignore lint/a11y/noAutofocus: command palette is intentionally focused on open
+          autoFocus
+          type="text"
+          value={query}
+          onChange={(e) => {
+            setQuery(e.target.value);
+            setCursor(0);
+          }}
+          placeholder="Type a command…"
+          className="w-full px-5 h-12 bg-transparent border-b border-[var(--color-border)] text-sm text-[var(--color-text-primary)] placeholder:text-[var(--color-text-muted)] focus:outline-none"
+        />
+        <ul className="max-h-72 overflow-y-auto py-2">
+          {filtered.length === 0 ? (
+            <li className="px-5 py-3 text-sm text-[var(--color-text-muted)]">No matches.</li>
+          ) : (
+            filtered.map((a, i) => {
+              const Icon = a.icon;
+              const active = i === cursor;
+              return (
+                <li key={a.id}>
+                  <button
+                    type="button"
+                    onMouseEnter={() => setCursor(i)}
+                    onClick={() => runAt(i)}
+                    className={`w-full flex items-center gap-3 px-5 py-2.5 text-left transition-colors ${
+                      active
+                        ? 'bg-[var(--color-surface-active)]'
+                        : 'hover:bg-[var(--color-surface-hover)]'
+                    }`}
+                  >
+                    <Icon className="w-4 h-4 text-[var(--color-text-secondary)] shrink-0" />
+                    <span className="flex-1 min-w-0">
+                      <span className="block text-sm text-[var(--color-text-primary)]">
+                        {a.label}
+                      </span>
+                      <span className="block text-xs text-[var(--color-text-muted)]">{a.hint}</span>
+                    </span>
+                  </button>
+                </li>
+              );
+            })
+          )}
+        </ul>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/components/PreviewPane.tsx b/apps/desktop/src/renderer/src/components/PreviewPane.tsx
new file mode 100644
index 00000000..0aca9e40
--- /dev/null
+++ b/apps/desktop/src/renderer/src/components/PreviewPane.tsx
@@ -0,0 +1,48 @@
+import { buildSrcdoc } from '@open-codesign/runtime';
+import { EmptyState } from '../preview/EmptyState';
+import { ErrorState } from '../preview/ErrorState';
+import { LoadingState } from '../preview/LoadingState';
+import { useCodesignStore } from '../store';
+
+export interface PreviewPaneProps {
+  onPickStarter: (prompt: string) => void;
+}
+
+export function PreviewPane({ onPickStarter }: PreviewPaneProps) {
+  const previewHtml = useCodesignStore((s) => s.previewHtml);
+  const isGenerating = useCodesignStore((s) => s.isGenerating);
+  const errorMessage = useCodesignStore((s) => s.errorMessage);
+  const retry = useCodesignStore((s) => s.retryLastPrompt);
+  const clearError = useCodesignStore((s) => s.clearError);
+
+  let body: React.ReactNode;
+  if (errorMessage) {
+    body = (
+      <ErrorState
+        message={errorMessage}
+        onRetry={() => {
+          void retry();
+        }}
+        onDismiss={clearError}
+      />
+    );
+  } else if (isGenerating) {
+    body = <LoadingState />;
+  } else if (previewHtml) {
+    body = (
+      <div className="h-full p-6">
+        <iframe
+          key={previewHtml.length}
+          title="design-preview"
+          sandbox="allow-scripts"
+          srcDoc={buildSrcdoc(previewHtml)}
+          className="w-full h-full bg-white rounded-[var(--radius-2xl)] shadow-[var(--shadow-card)] border border-[var(--color-border)]"
+        />
+      </div>
+    );
+  } else {
+    body = <EmptyState onPickStarter={onPickStarter} />;
+  }
+
+  return <div className="flex-1 overflow-auto">{body}</div>;
+}
diff --git a/apps/desktop/src/renderer/src/components/Settings.tsx b/apps/desktop/src/renderer/src/components/Settings.tsx
new file mode 100644
index 00000000..e6f6e46e
--- /dev/null
+++ b/apps/desktop/src/renderer/src/components/Settings.tsx
@@ -0,0 +1,168 @@
+import { Button } from '@open-codesign/ui';
+import { Cpu, FolderOpen, Palette, Settings as SettingsIcon, Sliders, X } from 'lucide-react';
+import { useState } from 'react';
+import { useCodesignStore } from '../store';
+
+type Tab = 'models' | 'appearance' | 'storage' | 'advanced';
+
+const TABS: ReadonlyArray<{ id: Tab; label: string; icon: typeof Cpu }> = [
+  { id: 'models', label: 'Models', icon: Cpu },
+  { id: 'appearance', label: 'Appearance', icon: Palette },
+  { id: 'storage', label: 'Storage', icon: FolderOpen },
+  { id: 'advanced', label: 'Advanced', icon: Sliders },
+];
+
+const CONFIG_PATH = '~/.config/open-codesign/config.toml';
+
+function ModelsTab() {
+  return (
+    <div className="space-y-3">
+      <h3 className="text-sm font-semibold text-[var(--color-text-primary)]">Providers</h3>
+      <p className="text-sm text-[var(--color-text-secondary)]">
+        Provider key entry will land with the onboarding flow. Until then, keys can be set in the
+        config file directly.
+      </p>
+      <div className="rounded-[var(--radius-md)] border border-dashed border-[var(--color-border)] p-4 text-sm text-[var(--color-text-muted)]">
+        Coming soon: Anthropic, OpenAI, Google, OpenRouter free tier.
+      </div>
+    </div>
+  );
+}
+
+function AppearanceTab() {
+  const theme = useCodesignStore((s) => s.theme);
+  const setTheme = useCodesignStore((s) => s.setTheme);
+  return (
+    <div className="space-y-4">
+      <div>
+        <h3 className="text-sm font-semibold text-[var(--color-text-primary)]">Theme</h3>
+        <p className="text-xs text-[var(--color-text-muted)] mt-1">
+          Pick a base palette. Choice persists across restarts.
+        </p>
+      </div>
+      <div className="grid grid-cols-2 gap-3">
+        {(['light', 'dark'] as const).map((t) => {
+          const active = theme === t;
+          return (
+            <button
+              key={t}
+              type="button"
+              onClick={() => setTheme(t)}
+              className={`text-left p-4 rounded-[var(--radius-lg)] border transition-colors ${
+                active
+                  ? 'border-[var(--color-accent)] bg-[var(--color-accent-muted)]'
+                  : 'border-[var(--color-border)] bg-[var(--color-surface)] hover:bg-[var(--color-surface-hover)]'
+              }`}
+            >
+              <div className="text-sm font-medium text-[var(--color-text-primary)] capitalize">
+                {t}
+              </div>
+              <div className="text-xs text-[var(--color-text-muted)] mt-1">
+                {t === 'light' ? 'Warm beige, soft shadows' : 'Deep neutral, low glare'}
+              </div>
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+function StorageTab() {
+  return (
+    <div className="space-y-4">
+      <div>
+        <h3 className="text-sm font-semibold text-[var(--color-text-primary)]">Config file</h3>
+        <p className="text-xs text-[var(--color-text-muted)] mt-1">
+          All settings live in a single TOML file you can read or edit yourself.
+        </p>
+      </div>
+      <code className="block px-3 py-2 rounded-[var(--radius-md)] bg-[var(--color-surface-muted)] border border-[var(--color-border)] text-xs text-[var(--color-text-primary)]">
+        {CONFIG_PATH}
+      </code>
+      <p className="text-xs text-[var(--color-text-secondary)]">
+        Designs and history are stored locally in SQLite under the same directory.
+      </p>
+    </div>
+  );
+}
+
+function AdvancedTab() {
+  return (
+    <div className="rounded-[var(--radius-md)] border border-dashed border-[var(--color-border)] p-6 text-sm text-[var(--color-text-muted)]">
+      Advanced options will appear here as the app grows. Nothing to configure yet.
+    </div>
+  );
+}
+
+export function Settings() {
+  const open = useCodesignStore((s) => s.settingsOpen);
+  const close = useCodesignStore((s) => s.closeSettings);
+  const [tab, setTab] = useState<Tab>('appearance');
+  if (!open) return null;
+  return (
+    <div
+      // biome-ignore lint/a11y/useSemanticElements: native <dialog> top-layer rendering interferes with our overlay stack
+      role="dialog"
+      aria-modal="true"
+      aria-label="Settings"
+      className="fixed inset-0 z-50 flex items-center justify-center p-6 bg-[var(--color-overlay)] animate-[overlay-in_120ms_ease-out]"
+      onClick={close}
+      onKeyDown={(e) => {
+        if (e.key === 'Escape') close();
+      }}
+    >
+      <div
+        className="w-full max-w-3xl h-[32rem] rounded-[var(--radius-2xl)] bg-[var(--color-background)] border border-[var(--color-border)] shadow-[var(--shadow-elevated)] grid grid-cols-[12rem_1fr] overflow-hidden animate-[panel-in_160ms_ease-out]"
+        onClick={(e) => e.stopPropagation()}
+        onKeyDown={(e) => e.stopPropagation()}
+        role="document"
+      >
+        <aside className="bg-[var(--color-background-secondary)] border-r border-[var(--color-border)] p-3">
+          <div className="flex items-center gap-2 px-2 py-2 mb-2">
+            <SettingsIcon className="w-4 h-4 text-[var(--color-text-secondary)]" />
+            <span className="text-sm font-semibold text-[var(--color-text-primary)]">Settings</span>
+          </div>
+          <nav className="space-y-1">
+            {TABS.map((t) => {
+              const Icon = t.icon;
+              const active = tab === t.id;
+              return (
+                <button
+                  key={t.id}
+                  type="button"
+                  onClick={() => setTab(t.id)}
+                  className={`w-full flex items-center gap-2 px-2 py-1.5 rounded-[var(--radius-md)] text-sm transition-colors ${
+                    active
+                      ? 'bg-[var(--color-surface-active)] text-[var(--color-text-primary)]'
+                      : 'text-[var(--color-text-secondary)] hover:bg-[var(--color-surface-hover)]'
+                  }`}
+                >
+                  <Icon className="w-4 h-4" />
+                  {t.label}
+                </button>
+              );
+            })}
+          </nav>
+        </aside>
+
+        <section className="flex flex-col">
+          <header className="flex items-center justify-between px-5 h-12 border-b border-[var(--color-border)]">
+            <h2 className="text-sm font-semibold text-[var(--color-text-primary)] capitalize">
+              {tab}
+            </h2>
+            <Button variant="ghost" size="sm" onClick={close} aria-label="Close settings">
+              <X className="w-4 h-4" />
+            </Button>
+          </header>
+          <div className="flex-1 overflow-y-auto p-6">
+            {tab === 'models' ? <ModelsTab /> : null}
+            {tab === 'appearance' ? <AppearanceTab /> : null}
+            {tab === 'storage' ? <StorageTab /> : null}
+            {tab === 'advanced' ? <AdvancedTab /> : null}
+          </div>
+        </section>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/components/Sidebar.tsx b/apps/desktop/src/renderer/src/components/Sidebar.tsx
new file mode 100644
index 00000000..8b5ccfea
--- /dev/null
+++ b/apps/desktop/src/renderer/src/components/Sidebar.tsx
@@ -0,0 +1,68 @@
+import { Button } from '@open-codesign/ui';
+import { Send } from 'lucide-react';
+import { useEffect, useRef } from 'react';
+import { useCodesignStore } from '../store';
+
+export interface SidebarProps {
+  prompt: string;
+  setPrompt: (value: string) => void;
+  onSubmit: () => void;
+}
+
+export function Sidebar({ prompt, setPrompt, onSubmit }: SidebarProps) {
+  const messages = useCodesignStore((s) => s.messages);
+  const isGenerating = useCodesignStore((s) => s.isGenerating);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    inputRef.current?.focus();
+  }, []);
+
+  function handleSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    onSubmit();
+  }
+
+  return (
+    <aside className="flex flex-col border-r border-[var(--color-border)] bg-[var(--color-background-secondary)]">
+      <div className="flex-1 overflow-y-auto px-5 py-4 space-y-3">
+        {messages.length === 0 ? (
+          <p className="text-sm text-[var(--color-text-muted)] px-1">
+            Start a conversation. Try a starter from the preview pane, or type your own brief.
+          </p>
+        ) : (
+          messages.map((m, i) => (
+            <div
+              key={`${m.role}-${i}`}
+              className={`px-3 py-2 rounded-[var(--radius-md)] text-sm ${
+                m.role === 'user'
+                  ? 'bg-[var(--color-accent-muted)] text-[var(--color-text-primary)]'
+                  : 'bg-[var(--color-surface)] border border-[var(--color-border)] text-[var(--color-text-primary)]'
+              }`}
+            >
+              {m.content}
+            </div>
+          ))
+        )}
+      </div>
+
+      <form
+        onSubmit={handleSubmit}
+        className="border-t border-[var(--color-border)] p-3 flex gap-2"
+      >
+        <input
+          ref={inputRef}
+          type="text"
+          value={prompt}
+          onChange={(e) => setPrompt(e.target.value)}
+          placeholder="Describe what to design…"
+          disabled={isGenerating}
+          className="flex-1 px-3 py-2 rounded-[var(--radius-md)] bg-[var(--color-surface)] border border-[var(--color-border)] text-sm text-[var(--color-text-primary)] placeholder:text-[var(--color-text-muted)] focus:outline-none focus:border-[var(--color-accent)]"
+        />
+        <Button type="submit" size="md" disabled={isGenerating || !prompt.trim()}>
+          <Send className="w-4 h-4" />
+        </Button>
+      </form>
+    </aside>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/components/ThemeToggle.tsx b/apps/desktop/src/renderer/src/components/ThemeToggle.tsx
new file mode 100644
index 00000000..804bb753
--- /dev/null
+++ b/apps/desktop/src/renderer/src/components/ThemeToggle.tsx
@@ -0,0 +1,16 @@
+import { IconButton, Tooltip } from '@open-codesign/ui';
+import { Moon, Sun } from 'lucide-react';
+import { useCodesignStore } from '../store';
+
+export function ThemeToggle() {
+  const theme = useCodesignStore((s) => s.theme);
+  const toggle = useCodesignStore((s) => s.toggleTheme);
+  const isDark = theme === 'dark';
+  return (
+    <Tooltip label={isDark ? 'Switch to light' : 'Switch to dark'}>
+      <IconButton label="Toggle theme" onClick={toggle}>
+        {isDark ? <Sun className="w-4 h-4" /> : <Moon className="w-4 h-4" />}
+      </IconButton>
+    </Tooltip>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/components/Toast.tsx b/apps/desktop/src/renderer/src/components/Toast.tsx
new file mode 100644
index 00000000..15c7c872
--- /dev/null
+++ b/apps/desktop/src/renderer/src/components/Toast.tsx
@@ -0,0 +1,64 @@
+import { CheckCircle2, Info, X, XCircle } from 'lucide-react';
+import { useCodesignStore } from '../store';
+import type { Toast as ToastModel, ToastVariant } from '../store';
+
+export function useToast() {
+  const push = useCodesignStore((s) => s.pushToast);
+  const dismiss = useCodesignStore((s) => s.dismissToast);
+  return { push, dismiss };
+}
+
+const iconFor: Record<ToastVariant, typeof CheckCircle2> = {
+  success: CheckCircle2,
+  error: XCircle,
+  info: Info,
+};
+
+const accentFor: Record<ToastVariant, string> = {
+  success: 'var(--color-toast-success)',
+  error: 'var(--color-toast-error)',
+  info: 'var(--color-accent)',
+};
+
+function ToastItem({ toast }: { toast: ToastModel }) {
+  const dismiss = useCodesignStore((s) => s.dismissToast);
+  const Icon = iconFor[toast.variant];
+  return (
+    <output className="flex items-start gap-3 w-80 px-4 py-3 rounded-[var(--radius-lg)] bg-[var(--color-surface)] border border-[var(--color-border)] shadow-[var(--shadow-elevated)] animate-[toast-in_180ms_ease-out]">
+      <Icon className="w-5 h-5 mt-0.5 shrink-0" style={{ color: accentFor[toast.variant] }} />
+      <div className="flex-1 min-w-0">
+        <div className="text-sm font-medium text-[var(--color-text-primary)]">{toast.title}</div>
+        {toast.description ? (
+          <div className="text-xs text-[var(--color-text-secondary)] mt-0.5 break-words">
+            {toast.description}
+          </div>
+        ) : null}
+      </div>
+      <button
+        type="button"
+        aria-label="Dismiss notification"
+        onClick={() => dismiss(toast.id)}
+        className="text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] transition-colors"
+      >
+        <X className="w-4 h-4" />
+      </button>
+    </output>
+  );
+}
+
+export function ToastViewport() {
+  const toasts = useCodesignStore((s) => s.toasts);
+  if (toasts.length === 0) return null;
+  return (
+    <div
+      aria-live="polite"
+      className="pointer-events-none fixed bottom-4 right-4 z-[60] flex flex-col gap-2 items-end"
+    >
+      {toasts.map((t) => (
+        <div key={t.id} className="pointer-events-auto">
+          <ToastItem toast={t} />
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/components/TopBar.tsx b/apps/desktop/src/renderer/src/components/TopBar.tsx
new file mode 100644
index 00000000..d6fdd044
--- /dev/null
+++ b/apps/desktop/src/renderer/src/components/TopBar.tsx
@@ -0,0 +1,53 @@
+import { IconButton, Tooltip } from '@open-codesign/ui';
+import { Command, Settings as SettingsIcon, Sparkles } from 'lucide-react';
+import type { CSSProperties } from 'react';
+import { useCodesignStore } from '../store';
+import { ThemeToggle } from './ThemeToggle';
+
+const dragRegion: CSSProperties = { WebkitAppRegion: 'drag' } as CSSProperties;
+const noDragRegion: CSSProperties = { WebkitAppRegion: 'no-drag' } as CSSProperties;
+
+export function TopBar() {
+  const previewHtml = useCodesignStore((s) => s.previewHtml);
+  const isGenerating = useCodesignStore((s) => s.isGenerating);
+  const errorMessage = useCodesignStore((s) => s.errorMessage);
+  const openSettings = useCodesignStore((s) => s.openSettings);
+  const openCommandPalette = useCodesignStore((s) => s.openCommandPalette);
+
+  let crumb = 'Untitled design';
+  if (errorMessage) crumb = 'Error';
+  else if (isGenerating) crumb = 'Generating…';
+  else if (previewHtml) crumb = 'Preview ready';
+
+  return (
+    <header
+      className="h-11 shrink-0 flex items-center justify-between px-4 border-b border-[var(--color-border)] bg-[var(--color-background)] select-none"
+      style={dragRegion}
+    >
+      <div className="flex items-center gap-3 pl-16 min-w-0">
+        <div className="flex items-center gap-2">
+          <Sparkles className="w-4 h-4 text-[var(--color-accent)]" />
+          <span className="text-sm font-semibold text-[var(--color-text-primary)]">
+            open-codesign
+          </span>
+        </div>
+        <span className="text-[var(--color-text-muted)]">/</span>
+        <span className="text-sm text-[var(--color-text-secondary)] truncate">{crumb}</span>
+      </div>
+
+      <div className="flex items-center gap-1" style={noDragRegion}>
+        <Tooltip label="Command palette  ⌘K">
+          <IconButton label="Open command palette" size="sm" onClick={openCommandPalette}>
+            <Command className="w-4 h-4" />
+          </IconButton>
+        </Tooltip>
+        <ThemeToggle />
+        <Tooltip label="Settings  ⌘,">
+          <IconButton label="Open settings" size="sm" onClick={openSettings}>
+            <SettingsIcon className="w-4 h-4" />
+          </IconButton>
+        </Tooltip>
+      </div>
+    </header>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/hooks/useKeyboard.ts b/apps/desktop/src/renderer/src/hooks/useKeyboard.ts
new file mode 100644
index 00000000..3ae689d6
--- /dev/null
+++ b/apps/desktop/src/renderer/src/hooks/useKeyboard.ts
@@ -0,0 +1,45 @@
+import { useEffect } from 'react';
+
+export interface KeyBinding {
+  combo: string;
+  handler: (e: KeyboardEvent) => void;
+  preventDefault?: boolean;
+}
+
+function matches(e: KeyboardEvent, combo: string): boolean {
+  const parts = combo
+    .toLowerCase()
+    .split('+')
+    .map((p) => p.trim());
+  const expectMod = parts.includes('mod');
+  const expectShift = parts.includes('shift');
+  const expectAlt = parts.includes('alt');
+  const key = parts[parts.length - 1] ?? '';
+
+  const modPressed = e.metaKey || e.ctrlKey;
+  if (expectMod !== modPressed) return false;
+  if (expectShift !== e.shiftKey) return false;
+  if (expectAlt !== e.altKey) return false;
+
+  const eventKey = e.key.toLowerCase();
+  if (key === 'enter') return eventKey === 'enter';
+  if (key === 'escape' || key === 'esc') return eventKey === 'escape';
+  if (key === ',') return eventKey === ',';
+  return eventKey === key;
+}
+
+export function useKeyboard(bindings: KeyBinding[]) {
+  useEffect(() => {
+    function onKeyDown(e: KeyboardEvent) {
+      for (const b of bindings) {
+        if (matches(e, b.combo)) {
+          if (b.preventDefault !== false) e.preventDefault();
+          b.handler(e);
+          return;
+        }
+      }
+    }
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, [bindings]);
+}
diff --git a/apps/desktop/src/renderer/src/index.css b/apps/desktop/src/renderer/src/index.css
index 0a997d3c..c471c6be 100644
--- a/apps/desktop/src/renderer/src/index.css
+++ b/apps/desktop/src/renderer/src/index.css
@@ -21,3 +21,54 @@ kbd,
 pre {
   font-family: var(--font-mono);
 }
+
+@keyframes overlay-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes panel-in {
+  from {
+    opacity: 0;
+    transform: translateY(0.5rem) scale(0.98);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+@keyframes toast-in {
+  from {
+    opacity: 0;
+    transform: translateY(0.5rem);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes shimmer-pulse {
+  0% {
+    background-position: -200% 0;
+  }
+  100% {
+    background-position: 200% 0;
+  }
+}
+
+.shimmer {
+  background-image: linear-gradient(
+    90deg,
+    var(--color-surface-muted) 0%,
+    var(--color-surface-hover) 50%,
+    var(--color-surface-muted) 100%
+  );
+  background-size: 200% 100%;
+  animation: shimmer-pulse 1.6s linear infinite;
+}
diff --git a/apps/desktop/src/renderer/src/preview/EmptyState.tsx b/apps/desktop/src/renderer/src/preview/EmptyState.tsx
new file mode 100644
index 00000000..c356d80f
--- /dev/null
+++ b/apps/desktop/src/renderer/src/preview/EmptyState.tsx
@@ -0,0 +1,56 @@
+import { Sparkles } from 'lucide-react';
+
+export interface EmptyStateProps {
+  onPickStarter: (prompt: string) => void;
+}
+
+const STARTERS: ReadonlyArray<{ label: string; prompt: string }> = [
+  {
+    label: 'Mobile meditation app',
+    prompt:
+      'Design a mobile app prototype for a meditation app called Calm Spaces. Show a phone frame containing a home screen with a meditation list, play button, and progress tracker.',
+  },
+  {
+    label: 'B2B pitch deck',
+    prompt:
+      'Create a 6-slide B2B SaaS pitch deck for an AI workflow tool. Include problem, solution, market, demo screenshot, traction, and ask.',
+  },
+  {
+    label: 'Case study one-pager',
+    prompt:
+      'Create a one-page client case study with hero metrics, a CEO quote, and a logo placeholder. Clean, minimal, dark theme.',
+  },
+];
+
+export function EmptyState({ onPickStarter }: EmptyStateProps) {
+  return (
+    <div className="h-full flex items-center justify-center px-6">
+      <div className="text-center max-w-md">
+        <div className="relative w-20 h-20 mx-auto mb-5">
+          <div className="absolute inset-0 rounded-full bg-[var(--color-accent-muted)] blur-xl opacity-70" />
+          <div className="relative w-20 h-20 rounded-full bg-[var(--color-surface)] border border-[var(--color-border)] flex items-center justify-center shadow-[var(--shadow-card)]">
+            <Sparkles className="w-8 h-8 text-[var(--color-accent)]" />
+          </div>
+        </div>
+        <h2 className="text-xl font-semibold text-[var(--color-text-primary)] mb-2">
+          Design with AI
+        </h2>
+        <p className="text-sm text-[var(--color-text-secondary)] mb-6">
+          Describe what you want to build, or start from one of these:
+        </p>
+        <div className="flex flex-wrap gap-2 justify-center">
+          {STARTERS.map((s) => (
+            <button
+              key={s.label}
+              type="button"
+              onClick={() => onPickStarter(s.prompt)}
+              className="px-3 py-1.5 rounded-full text-xs font-medium bg-[var(--color-surface)] border border-[var(--color-border)] text-[var(--color-text-secondary)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text-primary)] transition-colors"
+            >
+              {s.label}
+            </button>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/preview/ErrorState.tsx b/apps/desktop/src/renderer/src/preview/ErrorState.tsx
new file mode 100644
index 00000000..c285457e
--- /dev/null
+++ b/apps/desktop/src/renderer/src/preview/ErrorState.tsx
@@ -0,0 +1,57 @@
+import { Button } from '@open-codesign/ui';
+import { AlertTriangle, Copy, RotateCw } from 'lucide-react';
+import { useState } from 'react';
+
+export interface ErrorStateProps {
+  message: string;
+  onRetry: () => void;
+  onDismiss?: () => void;
+}
+
+export function ErrorState({ message, onRetry, onDismiss }: ErrorStateProps) {
+  const [copied, setCopied] = useState(false);
+
+  async function copy() {
+    await navigator.clipboard.writeText(message);
+    setCopied(true);
+    window.setTimeout(() => setCopied(false), 1800);
+  }
+
+  return (
+    <div className="h-full flex items-center justify-center p-6">
+      <div className="max-w-md w-full rounded-[var(--radius-2xl)] bg-[var(--color-surface)] border border-[var(--color-border)] shadow-[var(--shadow-card)] p-6">
+        <div className="flex items-start gap-3 mb-4">
+          <div className="w-10 h-10 rounded-full bg-[var(--color-accent-muted)] flex items-center justify-center shrink-0">
+            <AlertTriangle className="w-5 h-5" style={{ color: 'var(--color-error)' }} />
+          </div>
+          <div className="flex-1 min-w-0">
+            <h3 className="text-base font-semibold text-[var(--color-text-primary)]">
+              Generation failed
+            </h3>
+            <p className="text-sm text-[var(--color-text-secondary)] mt-1">
+              The model returned an error. You can retry or copy the details below.
+            </p>
+          </div>
+        </div>
+        <pre className="text-xs text-[var(--color-text-secondary)] bg-[var(--color-surface-muted)] border border-[var(--color-border)] rounded-[var(--radius-md)] p-3 mb-4 max-h-32 overflow-auto whitespace-pre-wrap break-words">
+          {message}
+        </pre>
+        <div className="flex items-center gap-2 justify-end">
+          {onDismiss ? (
+            <Button variant="ghost" size="sm" onClick={onDismiss}>
+              Dismiss
+            </Button>
+          ) : null}
+          <Button variant="secondary" size="sm" onClick={copy}>
+            <Copy className="w-4 h-4" />
+            {copied ? 'Copied' : 'Copy Error'}
+          </Button>
+          <Button variant="primary" size="sm" onClick={onRetry}>
+            <RotateCw className="w-4 h-4" />
+            Retry
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/preview/LoadingState.tsx b/apps/desktop/src/renderer/src/preview/LoadingState.tsx
new file mode 100644
index 00000000..67762f81
--- /dev/null
+++ b/apps/desktop/src/renderer/src/preview/LoadingState.tsx
@@ -0,0 +1,22 @@
+export function LoadingState() {
+  return (
+    <div className="h-full p-6">
+      <div className="h-full w-full rounded-[var(--radius-2xl)] border border-[var(--color-border)] bg-[var(--color-surface)] overflow-hidden flex flex-col">
+        <div className="px-6 py-5 border-b border-[var(--color-border-subtle)] space-y-3">
+          <div className="shimmer h-4 w-40 rounded-[var(--radius-sm)]" />
+          <div className="shimmer h-3 w-64 rounded-[var(--radius-sm)]" />
+        </div>
+        <div className="flex-1 grid grid-cols-3 gap-4 p-6">
+          <div className="shimmer rounded-[var(--radius-lg)]" />
+          <div className="shimmer rounded-[var(--radius-lg)]" />
+          <div className="shimmer rounded-[var(--radius-lg)]" />
+        </div>
+        <div className="px-6 py-5 border-t border-[var(--color-border-subtle)] flex items-center gap-3">
+          <div className="shimmer h-3 w-24 rounded-[var(--radius-sm)]" />
+          <div className="shimmer h-3 flex-1 rounded-[var(--radius-sm)]" />
+          <div className="shimmer h-8 w-20 rounded-[var(--radius-md)]" />
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/store.ts b/apps/desktop/src/renderer/src/store.ts
index f6e701d6..f00e08bf 100644
--- a/apps/desktop/src/renderer/src/store.ts
+++ b/apps/desktop/src/renderer/src/store.ts
@@ -8,12 +8,67 @@ declare global {
   }
 }
 
+export type ToastVariant = 'success' | 'error' | 'info';
+
+export interface Toast {
+  id: string;
+  variant: ToastVariant;
+  title: string;
+  description?: string;
+}
+
+export type Theme = 'light' | 'dark';
+
 interface CodesignState {
   messages: ChatMessage[];
   previewHtml: string | null;
   isGenerating: boolean;
   errorMessage: string | null;
+  lastError: string | null;
+
+  theme: Theme;
+  settingsOpen: boolean;
+  commandPaletteOpen: boolean;
+  toasts: Toast[];
+
   sendPrompt: (prompt: string) => Promise<void>;
+  retryLastPrompt: () => Promise<void>;
+  clearError: () => void;
+
+  setTheme: (theme: Theme) => void;
+  toggleTheme: () => void;
+  openSettings: () => void;
+  closeSettings: () => void;
+  openCommandPalette: () => void;
+  closeCommandPalette: () => void;
+
+  pushToast: (toast: Omit<Toast, 'id'>) => string;
+  dismissToast: (id: string) => void;
+}
+
+const THEME_STORAGE_KEY = 'open-codesign:theme';
+
+function readInitialTheme(): Theme {
+  if (typeof window === 'undefined') return 'light';
+  const stored = window.localStorage.getItem(THEME_STORAGE_KEY);
+  if (stored === 'light' || stored === 'dark') return stored;
+  return 'light';
+}
+
+function applyThemeClass(theme: Theme) {
+  if (typeof document === 'undefined') return;
+  const root = document.documentElement;
+  if (theme === 'dark') root.classList.add('dark');
+  else root.classList.remove('dark');
+}
+
+function persistTheme(theme: Theme) {
+  if (typeof window === 'undefined') return;
+  window.localStorage.setItem(THEME_STORAGE_KEY, theme);
+}
+
+function newId(): string {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
 }
 
 export const useCodesignStore = create<CodesignState>((set, get) => ({
@@ -21,11 +76,19 @@ export const useCodesignStore = create<CodesignState>((set, get) => ({
   previewHtml: null,
   isGenerating: false,
   errorMessage: null,
+  lastError: null,
+
+  theme: readInitialTheme(),
+  settingsOpen: false,
+  commandPaletteOpen: false,
+  toasts: [],
 
   async sendPrompt(prompt: string) {
     if (get().isGenerating) return;
     if (!window.codesign) {
-      set({ errorMessage: 'Renderer is not connected to the main process.' });
+      const msg = 'Renderer is not connected to the main process.';
+      set({ errorMessage: msg, lastError: msg });
+      get().pushToast({ variant: 'error', title: 'Generation failed', description: msg });
       return;
     }
 
@@ -36,8 +99,6 @@ export const useCodesignStore = create<CodesignState>((set, get) => ({
       errorMessage: null,
     }));
 
-    // Tier 1 wiring: hardcoded provider/model and key-from-env until the
-    // onboarding flow lands. The real flow will read from the keychain.
     const apiKey = '';
     if (!apiKey) {
       set((s) => ({
@@ -68,13 +129,68 @@ export const useCodesignStore = create<CodesignState>((set, get) => ({
         previewHtml: firstArtifact?.content ?? s.previewHtml,
         isGenerating: false,
       }));
+      get().pushToast({ variant: 'success', title: 'Design ready' });
     } catch (err) {
       const msg = err instanceof Error ? err.message : 'Unknown error';
       set((s) => ({
         messages: [...s.messages, { role: 'assistant', content: `Error: ${msg}` }],
         isGenerating: false,
         errorMessage: msg,
+        lastError: msg,
       }));
+      get().pushToast({ variant: 'error', title: 'Generation failed', description: msg });
     }
   },
+
+  async retryLastPrompt() {
+    const lastUser = [...get().messages].reverse().find((m) => m.role === 'user');
+    if (!lastUser) return;
+    set({ errorMessage: null });
+    await get().sendPrompt(lastUser.content);
+  },
+
+  clearError() {
+    set({ errorMessage: null });
+  },
+
+  setTheme(theme) {
+    applyThemeClass(theme);
+    persistTheme(theme);
+    set({ theme });
+  },
+
+  toggleTheme() {
+    const next: Theme = get().theme === 'dark' ? 'light' : 'dark';
+    get().setTheme(next);
+  },
+
+  openSettings() {
+    set({ settingsOpen: true, commandPaletteOpen: false });
+  },
+  closeSettings() {
+    set({ settingsOpen: false });
+  },
+
+  openCommandPalette() {
+    set({ commandPaletteOpen: true, settingsOpen: false });
+  },
+  closeCommandPalette() {
+    set({ commandPaletteOpen: false });
+  },
+
+  pushToast(toast) {
+    const id = newId();
+    const next: Toast = { id, ...toast };
+    set((s) => ({ toasts: [...s.toasts, next] }));
+    if (typeof window !== 'undefined') {
+      window.setTimeout(() => {
+        get().dismissToast(id);
+      }, 4000);
+    }
+    return id;
+  },
+
+  dismissToast(id) {
+    set((s) => ({ toasts: s.toasts.filter((t) => t.id !== id) }));
+  },
 }));