feat: unify card runtime and event-driven web ui

THEMING.md

@@ -0,0 +1,50 @@
+# Theming
+
+The app theme is driven by shared CSS custom properties.
+
+## Source Of Truth
+
+- Theme presets live in `frontend/src/theme/themes.ts`.
+- The selected theme is persisted in local storage under `nanobot.theme`.
+- The active theme is applied to `document.documentElement` before the app renders.
+
+## How To Change The App Theme
+
+Edit or add a preset in `frontend/src/theme/themes.ts`:
+
+- `label`
+- `swatch`
+- `tokens`
+
+The picker in the conversation drawer reads directly from that file, so new presets appear automatically.
+
+## Card Theming
+
+Cards inherit the same variables as the app shell.
+
+Prefer these semantic token families:
+
+- `--theme-card-neutral-*`
+- `--theme-card-warm-*`
+- `--theme-card-success-*`
+- `--card-*`
+- `--helper-card-*`
+- `--theme-text*`
+- `--theme-border*`
+- `--theme-accent*`
+- `--theme-status-*`
+
+Do not hardcode generic shell colors like `#ffffff`, `#111827`, or app-background gradients in new cards.
+
+## Runtime Access
+
+Dynamic cards can read theme values through the runtime host:
+
+- `host.getThemeName()`
+- `host.getThemeValue("--theme-accent")`
+
+For values that should live-update when the theme changes, prefer CSS variables directly:
+
+```html
+<div style="color:var(--theme-card-neutral-text)"></div>
+```