Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(themes): registry browse, import, panel default, and Theme Studio (plan 60 Phase 2-4)

Juan Denise09a6c29484e
diff --git a/README.md b/README.md
index c1fbdc5f..01a0b13e 100644
--- a/README.md
+++ b/README.md
@@ -306,6 +306,8 @@ Full history: [ROADMAP.md](ROADMAP.md)
| [Deployment Guide](docs/DEPLOYMENT.md) | CLI commands and production deployment |
| [Agent](https://github.com/jhd3197/serverkit-agent) | Install & run the multi-server agent (Linux/Windows/macOS) — separate repo |
| [Extensions Registry](https://github.com/jhd3197/serverkit-extensions) | The curated extension marketplace `index.json` — separate repo |
+| [Theming](docs/THEMING.md) | Build & share panel themes — token reference, Theme Studio, and the submit flow |
+| [Themes Registry](https://github.com/jhd3197/serverkit-themes) | The curated community themes registry — separate repo |
| [Agent Pairing](docs/pairing.md) | Secure short-code agent enrollment |
| [API Reference](docs/API.md) | REST API endpoints |
| [New Features](docs/NEW_FEATURES.md) | Endpoint & page reference for the latest `dev` features |
diff --git a/ROADMAP.md b/ROADMAP.md
index 25720e9c..5f035ea4 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -10,6 +10,7 @@ This document outlines the development roadmap for ServerKit. Features are organ
### Recently Completed (v1.7.x)
+- **Themes & Theme Studio** - A gallery of color themes in Settings → Appearance (Paper, Nord Deep, Gruvbox, Phosphor, High Contrast, and the stock look), applied instantly and previewed live, kept as each user's personal choice on top of the dark/light toggle. Themes are data, not code — a small map of color tokens — so a built-in Theme Studio lets anyone edit colors over the live panel and export a shareable file, admins can set a panel-wide default or import a theme, and a public community registry installs themes with one click.
- **Deploy Console & Live Run Logs** - Every install and deploy lands on one full-page live console: streaming build output, a step timeline with per-step durations and a live elapsed timer, and failure cards showing the real error tail with plain-language hints and one-click retry. Backed by a unified batched run-log layer (database persistence + WebSocket push with a polling fallback).
- **New Service Wizard & Template Catalog** - Three-step service creation (Source / Connect / Review) backed by a server-side template catalog with one-click compose templates and Git-repo templates.
- **Extensions Platform Maturation** - Marketplace registry backed by standalone extension repos (Kubernetes, Automations, Analytics, Mail, GPU, CrowdSec, DNS server, and more), with built-in features progressively extracted to keep the default panel lean. Installed extensions that ship a prebuilt bundle now render their UI on a production panel with no rebuild.
diff --git a/docs/THEMING.md b/docs/THEMING.md
new file mode 100644
index 00000000..c3c1d04b
--- /dev/null
+++ b/docs/THEMING.md
@@ -0,0 +1,166 @@
+# Theming ServerKit
+
+A ServerKit theme is **data, not code**: a small JSON file that maps color
+tokens to values. There's no JavaScript, no build step, no permissions, and no
+sandbox — the whole panel is already painted through CSS custom properties, so a
+theme just supplies new values for them at runtime. Reviewing a theme is reading
+a diff of colors.
+
+- **Use a theme:** Settings → Appearance → **Theme**. Pick a card; it applies
+ instantly and stays your personal choice. The dark/light toggle keeps working
+ on top of it.
+- **Make a theme:** Settings → Appearance → **Create theme** (Theme Studio) —
+ edit colors over the live panel, then Export a `theme.json`, save it to this
+ panel, or submit it to the registry.
+- **Share a theme:** open a PR to the
+ [`serverkit-themes`](https://github.com/jhd3197/serverkit-themes) registry.
+ Merged = published.
+
+---
+
+## `theme.json` (schema_version 1)
+
+```jsonc
+{
+ "schema_version": 1,
+ "slug": "nord-deep", // required, kebab-case, unique, matches the folder
+ "name": "Nord Deep", // required, display name
+ "author": "your-handle", // GitHub handle
+ "version": "1.0.0",
+ "description": "Cool arctic blues.",
+ "base": "dark", // "dark" | "light" — which mode this is a skin OF
+ "tokens": {
+ "dark": { "--bg-body": "#2e3440", "--surface": "#3b4252", "…": "…" },
+ "light": { "…": "…" } // optional — omit and the stock light theme is used
+ },
+ "accent": "#88c0d0", // optional — the panel derives the accent ramp from this
+ "preview": ["#2e3440", "#3b4252", "#88c0d0", "#eceff4"] // 4 gallery swatches
+}
+```
+
+A **dark-only** theme omits `tokens.light` (the stock light theme is used when a
+user toggles to light). A **light-only** theme (`base: "light"`) omits
+`tokens.dark`. Provide both for a theme that should look intentional in either
+mode.
+
+---
+
+## The token whitelist
+
+A theme may set only these canonical tokens. You write ~37 names; the panel
+fans each out to the legacy `--bg-*/--text-*/--border-*` aliases automatically,
+so the whole UI tracks your theme. Accent tokens are **not** in this list — they
+are derived from the single top-level `accent` field.
+
+### Surfaces (colors)
+| Token | Paints |
+|---|---|
+| `--bg-body` | App background (behind everything) |
+| `--bg-sidebar` | Sidebar background |
+| `--surface` | Card / panel surface (→ `--bg-card`) |
+| `--surface-2` | Elevated / secondary surface (→ `--bg-elevated`, `--bg-secondary`) |
+| `--surface-3` | Tertiary surface (→ `--bg-tertiary`) |
+| `--surface-hover` | Hover surface (→ `--bg-hover`) |
+
+### Borders (colors)
+| Token | Paints |
+|---|---|
+| `--border` | Default border (→ `--border-default`) |
+| `--border-soft` | Subtle divider (→ `--border-subtle`) |
+| `--border-strong` | Active / strong border (→ `--border-active`, `--border-hover`) |
+
+### Text (colors)
+| Token | Paints |
+|---|---|
+| `--text` | Primary text (→ `--text-primary`) |
+| `--text-dim` | Secondary text (→ `--text-secondary`) |
+| `--text-faint` | Tertiary text (→ `--text-tertiary`) |
+| `--text-ghost` | Faintest text / placeholders |
+
+### Semantic (colors)
+`--green`, `--green-bg`, `--amber`, `--amber-bg`, `--red`, `--red-bg`,
+`--cyan`, `--cyan-bg`, `--violet`, `--violet-bg`.
+The `*-bg` tokens are the translucent wash behind the matching accent (use an
+`rgba()` at low alpha, e.g. `rgba(61,220,151,0.12)`).
+
+### Chrome
+| Token | Type | Paints |
+|---|---|---|
+| `--radius`, `--radius-sm`, `--radius-lg` | length | Corner radii |
+| `--sans`, `--mono` | font stack | UI + monospace fonts (bundled families only) |
+| `--shadow-sm`, `--shadow-md`, `--shadow-lg` | shadow | Elevation shadows |
+| `--scrollbar-track`, `--scrollbar-thumb`, `--scrollbar-thumb-hover` | color | Scrollbars |
+| `--bg-code`, `--text-code` | color | Code / terminal blocks |
+| `--grid-color` | color | The faint background grid |
+
+---
+
+## Value rules (enforced client-side, server-side, and in registry CI)
+
+- **Colors:** hex (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`), `rgb()/rgba()`,
+ `hsl()/hsla()`, or a bare CSS named color.
+- **Lengths:** a number with an optional `px/rem/em/%/vh/vw` unit (or `0`).
+- **Fonts:** a font-family stack using only the families the panel already ships
+ (IBM Plex Sans / Mono and the system fallbacks). **No `url()` — no remote
+ fonts.** Most themes should omit `--sans`/`--mono` entirely.
+- **Shadows:** standard `box-shadow` syntax, or `none`.
+- **Never allowed anywhere:** `url(`, `@`, `;`, `}`, `{`, `<`, `>`,
+ `expression(`, or `/*`. Values over 200 characters are rejected. Unknown
+ tokens are dropped.
+
+There is **no `custom_css` and no JavaScript** in a v1 theme. The moment
+arbitrary CSS enters, a theme becomes code (exfiltration via
+`background: url(...)`, UI spoofing) and the trust story collapses to the
+extension one. Themes stay data on purpose.
+
+Because every value is validated and applied per-token via
+`CSSStyleDeclaration.setProperty`, a theme can't break out of its declaration or
+smuggle a network request even if a validation rule is missed.
+
+---
+
+## Theme Studio (the authoring loop)
+
+Settings → Appearance → **Create theme**:
+
+1. **Start from** any installed theme to inherit its palette.
+2. Edit colors with grouped pickers — every change applies to the **live panel**
+ instantly, in the mode (dark/light) you're editing.
+3. Set the **accent** once; the panel derives the hover/bright/dim/wash ramp.
+4. **Export theme.json** (a valid, ready-to-share file), **Save to this panel**
+ (admins — adds it to the gallery), or **Submit to registry** (opens a
+ prefilled new-file PR against `serverkit-themes`).
+
+No tooling to install — the whole authoring loop lives in the panel.
+
+---
+
+## Submit to the registry
+
+The registry is the [`serverkit-themes`](https://github.com/jhd3197/serverkit-themes)
+repo. Themes live **in** the repo — submission is a PR, publication is a merge:
+
+1. Fork it. Add `themes/<slug>/theme.json` (or export one from Theme Studio).
+2. Run `node scripts/build-index.mjs` and commit the updated `index.json`.
+3. Open a PR. CI validates against the schema + token whitelist + value rules.
+4. A maintainer merges — panels pick it up on their next registry refresh.
+
+Operators can point a panel at a different registry with
+`SERVERKIT_THEMES_REGISTRY_URL` (unset = the public registry; set-but-empty =
+bundled seeds only). The panel is offline-tolerant: a failed fetch falls back to
+the last good cache, then to the themes bundled with the panel — the gallery
+never blanks.
+
+---
+
+## Notes & limits (v1)
+
+- **Charts, xterm terminal, and the code/diff viewers** read their own color
+ configs; they track the semantic tokens where feasible but are otherwise
+ documented as unthemed for v1.
+- **Hardcoded colors:** any page style not reading a token will ignore a skin.
+ The panel's styles route through tokens; if you spot a straggler, it's a bug
+ worth reporting.
+- **The token names never change** — themes ride the existing names, so a theme
+ authored today keeps working. A newer theme on an older panel degrades
+ gracefully (unknown tokens are simply dropped).
diff --git a/frontend/src/App.jsx b/frontend/src/App.jsx
index 7bbb6593..f37f0fb6 100644
--- a/frontend/src/App.jsx
+++ b/frontend/src/App.jsx
@@ -7,6 +7,7 @@ import { LayoutProvider } from './contexts/LayoutContext';
import { ResourceTierProvider } from './contexts/ResourceTierContext';
import { NotificationsProvider } from './contexts/NotificationsContext';
import { Toaster } from './components/ui/sonner';
+import ThemeSync from './components/ThemeSync';
import DashboardLayout from './layouts/DashboardLayout';
import AppLoader from './components/AppLoader';
import Dashboard from './pages/Dashboard';
@@ -486,6 +487,7 @@ function App() {
publicTitle via useAuth (branding), so it must sit under
the provider. It stays inside Router for useLocation. */}
<PageTitleUpdater />
+ <ThemeSync />
<ResourceTierProvider>
<ToastProvider>
<NotificationsProvider>
diff --git a/frontend/src/components/ThemeSync.jsx b/frontend/src/components/ThemeSync.jsx
new file mode 100644
index 00000000..19113eeb
--- /dev/null
+++ b/frontend/src/components/ThemeSync.jsx
@@ -0,0 +1,30 @@
+import { useEffect } from 'react';
+import { useAuth } from '../contexts/AuthContext';
+import { useTheme } from '../contexts/ThemeContext';
+import api from '../services/api';
+
+// Bridges auth → theme (plan 60). ThemeProvider sits above AuthProvider, so it
+// can't read auth state itself; this renders inside AuthProvider and, once the
+// user is signed in, loads the installed (registry/imported) themes and merges
+// them into the gallery. Renders nothing.
+const ThemeSync = () => {
+ const { isAuthenticated } = useAuth();
+ const { registerInstalledThemes } = useTheme();
+
+ useEffect(() => {
+ if (!isAuthenticated) return undefined;
+ let cancelled = false;
+ api.getInstalledThemes?.()
+ .then((data) => {
+ if (!cancelled && data && Array.isArray(data.themes)) {
+ registerInstalledThemes(data.themes);
+ }
+ })
+ .catch(() => { /* gallery still shows bundled seeds */ });
+ return () => { cancelled = true; };
+ }, [isAuthenticated, registerInstalledThemes]);
+
+ return null;
+};
+
+export default ThemeSync;
diff --git a/frontend/src/components/settings/AppearanceTab.jsx b/frontend/src/components/settings/AppearanceTab.jsx
index ef054723..4972d1c1 100644
--- a/frontend/src/components/settings/AppearanceTab.jsx
+++ b/frontend/src/components/settings/AppearanceTab.jsx
@@ -1,10 +1,17 @@
+import { useRef, useState } from 'react';
import { useTheme } from '../../contexts/ThemeContext';
+import { useAuth } from '../../contexts/AuthContext';
+import { useToast } from '../../contexts/ToastContext';
import useDashboardLayout from '../../hooks/useDashboardLayout';
-import { ChevronDown, ChevronUp, RotateCcw } from 'lucide-react';
+import { ChevronDown, ChevronUp, RotateCcw, Upload, Store } from 'lucide-react';
import { Button } from '@/components/ui/button';
import { Switch } from '@/components/ui/switch';
import useSettingFocus from '../../hooks/useSettingFocus';
import ThemeGallery from './ThemeGallery';
+import ThemeBrowseModal from './ThemeBrowseModal';
+import ThemeStudioModal from './ThemeStudioModal';
+import { Sparkles } from 'lucide-react';
+import api from '../../services/api';
const ACCENT_PRESETS = [
{ label: 'Indigo', color: '#6366f1' },
@@ -18,9 +25,32 @@ const ACCENT_PRESETS = [
];
const AppearanceTab = () => {
- const { theme, setTheme, accentColor, setAccentColor, hasCustomAccent, resetAccentColor } = useTheme();
+ const {
+ theme, setTheme, accentColor, setAccentColor, hasCustomAccent, resetAccentColor,
+ refreshInstalledThemes, setSkin,
+ } = useTheme();
+ const { user } = useAuth();
+ const toast = useToast();
const { widgets, toggleWidget, moveWidget, resetLayout } = useDashboardLayout();
const register = useSettingFocus();
+ const fileInputRef = useRef(null);
+ const [browseOpen, setBrowseOpen] = useState(false);
+ const [studioOpen, setStudioOpen] = useState(false);
+ const isAdmin = user?.role === 'admin';
+
+ const onImportFile = async (e) => {
+ const file = e.target.files?.[0];
+ e.target.value = ''; // allow re-selecting the same file
+ if (!file) return;
+ try {
+ const imported = await api.importThemeFile(file);
+ await refreshInstalledThemes();
+ if (imported?.slug) setSkin(imported.slug);
+ toast.success(`Imported theme "${imported?.name || imported?.slug}"`);
+ } catch (err) {
+ toast.error(err?.message || 'Could not import that theme.json');
+ }
+ };
return (
<div className="settings-section">
@@ -76,9 +106,40 @@ const AppearanceTab = () => {
</div>
<div {...register('appearance-theme-gallery', 'settings-card')}>
- <h3>Theme</h3>
- <p>Pick a color theme. Applies instantly and stays your personal choice; the dark/light toggle above still works on top of it.</p>
+ <div className="theme-gallery-header">
+ <div>
+ <h3>Theme</h3>
+ <p>Pick a color theme. Applies instantly and stays your personal choice; the dark/light toggle above still works on top of it.</p>
+ </div>
+ <div className="theme-gallery-actions">
+ <Button variant="outline" size="sm" onClick={() => setStudioOpen(true)}>
+ <Sparkles size={14} />
+ Create theme
+ </Button>
+ {isAdmin && (
+ <>
+ <input
+ ref={fileInputRef}
+ type="file"
+ accept="application/json,.json"
+ style={{ display: 'none' }}
+ onChange={onImportFile}
+ />
+ <Button variant="outline" size="sm" onClick={() => setBrowseOpen(true)}>
+ <Store size={14} />
+ Browse themes
+ </Button>
+ <Button variant="outline" size="sm" onClick={() => fileInputRef.current?.click()}>
+ <Upload size={14} />
+ Import theme.json
+ </Button>
+ </>
+ )}
+ </div>
+ </div>
<ThemeGallery />
+ <ThemeBrowseModal open={browseOpen} onOpenChange={setBrowseOpen} />
+ <ThemeStudioModal open={studioOpen} onOpenChange={setStudioOpen} />
</div>
<div {...register('appearance-accent-color', 'settings-card')}>
diff --git a/frontend/src/components/settings/ThemeBrowseModal.jsx b/frontend/src/components/settings/ThemeBrowseModal.jsx
new file mode 100644
index 00000000..559d2577
--- /dev/null
+++ b/frontend/src/components/settings/ThemeBrowseModal.jsx
@@ -0,0 +1,114 @@
+import { useEffect, useState } from 'react';
+import { Check, Download, Loader2 } from 'lucide-react';
+import {
+ Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription,
+} from '@/components/ui/dialog';
+import { useTheme } from '../../contexts/ThemeContext';
+import { useToast } from '../../contexts/ToastContext';
+import api from '../../services/api';
+
+// Browse & install community themes from the registry (plan 60, Phase 3).
+// Offline-tolerant: if the registry is unreachable the panel falls back to the
+// bundled index, so this never hard-fails — it just shows fewer (or no) cards.
+const ThemeBrowseModal = ({ open, onOpenChange }) => {
+ const { refreshInstalledThemes } = useTheme();
+ const toast = useToast();
+ const [loading, setLoading] = useState(false);
+ const [themes, setThemes] = useState([]);
+ const [source, setSource] = useState(null);
+ const [installing, setInstalling] = useState(null);
+
+ const load = async () => {
+ setLoading(true);
+ try {
+ const data = await api.getThemeRegistry();
+ setThemes(Array.isArray(data?.themes) ? data.themes : []);
+ setSource(data?.source || null);
+ } catch (e) {
+ toast.error(e?.message || 'Could not load the theme registry');
+ setThemes([]);
+ } finally {
+ setLoading(false);
+ }
+ };
+
+ useEffect(() => {
+ if (open) load();
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [open]);
+
+ const install = async (slug) => {
+ setInstalling(slug);
+ try {
+ await api.installRegistryTheme(slug);
+ await refreshInstalledThemes();
+ setThemes((prev) => prev.map((t) => (t.slug === slug ? { ...t, installed: true } : t)));
+ toast.success('Theme installed — find it in the gallery');
+ } catch (e) {
+ toast.error(e?.message || 'Could not install that theme');
+ } finally {
+ setInstalling(null);
+ }
+ };
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogContent className="theme-browse-modal">
+ <DialogHeader>
+ <DialogTitle>Browse themes</DialogTitle>
+ <DialogDescription>
+ Community themes from the registry. Installing one adds it to your gallery.
+ </DialogDescription>
+ </DialogHeader>
+
+ {loading ? (
+ <div className="theme-browse__state">
+ <Loader2 className="spin" size={18} /> Loading registry…
+ </div>
+ ) : themes.length === 0 ? (
+ <div className="theme-browse__state">
+ No community themes available right now.
+ {source === 'bundled' && ' (registry offline — showing bundled only)'}
+ </div>
+ ) : (
+ <div className="theme-browse__grid">
+ {themes.map((t) => {
+ const swatches = Array.isArray(t.preview) ? t.preview.slice(0, 4) : [];
+ return (
+ <div key={t.slug} className="theme-browse__card">
+ <div className="theme-browse__swatches">
+ {swatches.map((c, i) => (
+ <span key={i} style={{ background: c }} />
+ ))}
+ </div>
+ <div className="theme-browse__meta">
+ <span className="theme-browse__name">{t.name || t.slug}</span>
+ {t.author && <span className="theme-browse__author">by {t.author}</span>}
+ </div>
+ {t.description && <p className="theme-browse__desc">{t.description}</p>}
+ {t.installed ? (
+ <span className="theme-browse__installed"><Check size={13} /> Installed</span>
+ ) : (
+ <button
+ type="button"
+ className="theme-browse__install"
+ disabled={installing === t.slug}
+ onClick={() => install(t.slug)}
+ >
+ {installing === t.slug
+ ? <Loader2 className="spin" size={13} />
+ : <Download size={13} />}
+ Install
+ </button>
+ )}
+ </div>
+ );
+ })}
+ </div>
+ )}
+ </DialogContent>
+ </Dialog>
+ );
+};
+
+export default ThemeBrowseModal;
diff --git a/frontend/src/components/settings/ThemeGallery.jsx b/frontend/src/components/settings/ThemeGallery.jsx
index a83df965..d6919245 100644
--- a/frontend/src/components/settings/ThemeGallery.jsx
+++ b/frontend/src/components/settings/ThemeGallery.jsx
@@ -1,25 +1,71 @@
-import { Check } from 'lucide-react';
+import { useState } from 'react';
+import { Check, Star, Trash2 } from 'lucide-react';
import { useTheme } from '../../contexts/ThemeContext';
+import { useAuth } from '../../contexts/AuthContext';
+import { useToast } from '../../contexts/ToastContext';
import { DEFAULT_THEME_SLUG } from '../../data/bundledThemes';
+import api from '../../services/api';
// Theme Gallery — cards for every selectable skin (bundled seeds + installed).
-// Apply is instant (tokens are already local); hovering a card previews it live
-// and leaving restores the selected skin. Dark/light toggle stays orthogonal.
+// Apply is instant (tokens are already local); hovering previews live and
+// leaving restores the selected skin. Admins can additionally set the panel
+// default (what login/setup and new users get) and remove installed themes.
const ThemeGallery = () => {
- const { availableThemes, skin, setSkin, previewSkin, clearPreview } = useTheme();
+ const {
+ availableThemes, skin, setSkin, previewSkin, clearPreview,
+ panelDefaultSlug, refreshInstalledThemes, refreshPanelDefault,
+ } = useTheme();
+ const { user } = useAuth();
+ const toast = useToast();
+ const isAdmin = user?.role === 'admin';
+ const [busy, setBusy] = useState(null);
+
+ const setDefault = async (slug) => {
+ setBusy(slug);
+ try {
+ await api.setDefaultTheme(slug);
+ await refreshPanelDefault();
+ toast.success('Panel default theme updated');
+ } catch (e) {
+ toast.error(e?.message || 'Could not set the default theme');
+ } finally {
+ setBusy(null);
+ }
+ };
+
+ const removeTheme = async (slug) => {
+ setBusy(slug);
+ try {
+ await api.deleteTheme(slug);
+ await Promise.all([refreshInstalledThemes(), refreshPanelDefault()]);
+ toast.success('Theme removed');
+ } catch (e) {
+ toast.error(e?.message || 'Could not remove the theme');
+ } finally {
+ setBusy(null);
+ }
+ };
+
+ const select = (slug) => setSkin(slug);
return (
<div className="theme-gallery">
{availableThemes.map((t) => {
const isDefault = t.slug === DEFAULT_THEME_SLUG;
const active = skin === t.slug;
+ const isPanelDefault = t.slug === panelDefaultSlug;
+ const removable = t.installed && !t.builtin && !isDefault;
const swatches = Array.isArray(t.preview) ? t.preview.slice(0, 4) : [];
return (
- <button
- type="button"
+ <div
key={t.slug}
+ role="button"
+ tabIndex={0}
className={`theme-card${active ? ' theme-card--active' : ''}`}
- onClick={() => setSkin(t.slug)}
+ onClick={() => select(t.slug)}
+ onKeyDown={(e) => {
+ if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); select(t.slug); }
+ }}
onMouseEnter={() => previewSkin(isDefault ? null : t)}
onMouseLeave={clearPreview}
onFocus={() => previewSkin(isDefault ? null : t)}
@@ -41,12 +87,43 @@ const ThemeGallery = () => {
{t.description && (
<p className="theme-card__desc">{t.description}</p>
)}
- {active && (
- <span className="theme-card__applied">
- <Check size={13} /> Applied
- </span>
+ <div className="theme-card__footer">
+ {active && (
+ <span className="theme-card__applied">
+ <Check size={13} /> Applied
+ </span>
+ )}
+ {isPanelDefault && (
+ <span className="theme-card__default" title="Default for the whole panel">
+ <Star size={12} /> Panel default
+ </span>
+ )}
+ </div>
+ {isAdmin && (
+ <div className="theme-card__admin">
+ {!isPanelDefault && (
+ <button
+ type="button"
+ className="theme-card__admin-btn"
+ disabled={busy === t.slug}
+ onClick={(e) => { e.stopPropagation(); setDefault(t.slug); }}
+ >
+ <Star size={12} /> Set default
+ </button>
+ )}
+ {removable && (
+ <button
+ type="button"
+ className="theme-card__admin-btn theme-card__admin-btn--danger"
+ disabled={busy === t.slug}
+ onClick={(e) => { e.stopPropagation(); removeTheme(t.slug); }}
+ >
+ <Trash2 size={12} /> Remove
+ </button>
+ )}
+ </div>
)}
- </button>
+ </div>
);
})}
</div>
diff --git a/frontend/src/components/settings/ThemeStudioModal.jsx b/frontend/src/components/settings/ThemeStudioModal.jsx
new file mode 100644
index 00000000..ead013a0
--- /dev/null
+++ b/frontend/src/components/settings/ThemeStudioModal.jsx
@@ -0,0 +1,247 @@
+import { useEffect, useMemo, useState } from 'react';
+import { Download, Save, Github, Sparkles } from 'lucide-react';
+import {
+ Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription,
+} from '@/components/ui/dialog';
+import { Button } from '@/components/ui/button';
+import { useTheme } from '../../contexts/ThemeContext';
+import { useAuth } from '../../contexts/AuthContext';
+import { useToast } from '../../contexts/ToastContext';
+import { TOKEN_GROUPS, GROUP_LABELS, TOKEN_TYPE, sanitizeTokens } from '../../data/themeTokens';
+import { DEFAULT_THEME_SLUG, BUNDLED_THEME_MAP } from '../../data/bundledThemes';
+import api from '../../services/api';
+
+const REGISTRY_REPO = 'https://github.com/jhd3197/serverkit-themes';
+
+const slugify = (s) => String(s || '')
+ .toLowerCase().trim()
+ .replace(/[^a-z0-9]+/g, '-')
+ .replace(/^-+|-+$/g, '');
+
+// Seed the editor from a theme's tokens for the given mode; fall back to the
+// stock default so every picker starts with a real value.
+function seedTokens(theme, mode) {
+ const stock = BUNDLED_THEME_MAP[DEFAULT_THEME_SLUG]?.tokens?.[mode] || {};
+ const from = theme?.tokens?.[mode] || {};
+ return { ...stock, ...from };
+}
+
+// Theme Studio (plan 60, Phase 4) — the "SDK" for a data format is docs +
+// tooling. Edit colors over the LIVE panel (every change applies instantly via
+// the skin preview), start from any installed theme, then Export a valid
+// theme.json, Save it into this panel, or Submit it to the registry.
+const ThemeStudioModal = ({ open, onOpenChange }) => {
+ const { availableThemes, previewSkin, clearPreview, refreshInstalledThemes, setSkin } = useTheme();
+ const { user } = useAuth();
+ const toast = useToast();
+ const isAdmin = user?.role === 'admin';
+
+ const [name, setName] = useState('My Theme');
+ const [slug, setSlug] = useState('my-theme');
+ const [slugTouched, setSlugTouched] = useState(false);
+ const [base, setBase] = useState('dark');
+ const [editMode, setEditMode] = useState('dark');
+ const [accent, setAccent] = useState('#6d7cff');
+ const [darkTokens, setDarkTokens] = useState(() => seedTokens(null, 'dark'));
+ const [lightTokens, setLightTokens] = useState(() => seedTokens(null, 'light'));
+ const [saving, setSaving] = useState(false);
+
+ const activeTokens = editMode === 'light' ? lightTokens : darkTokens;
+ const setActiveTokens = editMode === 'light' ? setLightTokens : setDarkTokens;
+
+ // Build the in-progress theme object (used for live preview + export).
+ const workingTheme = useMemo(() => ({
+ schema_version: 1,
+ slug: slug || 'my-theme',
+ name: name || 'My Theme',
+ author: user?.username || '',
+ version: '1.0.0',
+ base,
+ tokens: { dark: sanitizeTokens(darkTokens), light: sanitizeTokens(lightTokens) },
+ accent,
+ preview: [
+ activeTokens['--bg-body'] || '#101218',
+ activeTokens['--surface'] || '#161922',
+ accent || '#6d7cff',
+ activeTokens['--text'] || '#e9ebf0',
+ ],
+ }), [slug, name, base, darkTokens, lightTokens, accent, activeTokens, user]);
+
+ // Live-apply the in-progress theme while the studio is open.
+ useEffect(() => {
+ if (open) previewSkin(workingTheme);
+ return () => { if (open) clearPreview(); };
+ }, [open, workingTheme, previewSkin, clearPreview]);
+
+ const startFrom = (fromSlug) => {
+ const theme = availableThemes.find((t) => t.slug === fromSlug);
+ if (!theme) return;
+ setDarkTokens(seedTokens(theme, 'dark'));
+ setLightTokens(seedTokens(theme, 'light'));
+ if (theme.base) setBase(theme.base);
+ if (theme.accent) setAccent(theme.accent);
+ };
+
+ const onNameChange = (v) => {
+ setName(v);
+ if (!slugTouched) setSlug(slugify(v));
+ };
+
+ const setToken = (token, value) => setActiveTokens((prev) => ({ ...prev, [token]: value }));
+
+ const download = () => {
+ const blob = new Blob([JSON.stringify(workingTheme, null, 2)], { type: 'application/json' });
+ const url = URL.createObjectURL(blob);
+ const a = document.createElement('a');
+ a.href = url;
+ a.download = `${workingTheme.slug || 'theme'}.json`;
+ a.click();
+ URL.revokeObjectURL(url);
+ toast.success('theme.json downloaded');
+ };
+
+ const saveToPanel = async () => {
+ if (workingTheme.slug === DEFAULT_THEME_SLUG) {
+ toast.error("'default' is reserved — choose another slug");
+ return;
+ }
+ setSaving(true);
+ try {
+ const saved = await api.importTheme(workingTheme, { source: 'studio' });
+ await refreshInstalledThemes();
+ if (saved?.slug) setSkin(saved.slug);
+ toast.success(`Saved "${saved?.name}" to this panel`);
+ onOpenChange(false);
+ } catch (e) {
+ toast.error(e?.message || 'Could not save the theme');
+ } finally {
+ setSaving(false);
+ }
+ };
+
+ const submitToRegistry = () => {
+ const filename = `themes/${workingTheme.slug || 'my-theme'}/theme.json`;
+ const value = encodeURIComponent(JSON.stringify(workingTheme, null, 2));
+ // GitHub "create new file" deep-link, prefilled with the theme.
+ const url = `${REGISTRY_REPO}/new/main?filename=${encodeURIComponent(filename)}&value=${value}`;
+ window.open(url, '_blank', 'noopener,noreferrer');
+ };
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogContent className="theme-studio">
+ <DialogHeader>
+ <DialogTitle>Theme Studio</DialogTitle>
+ <DialogDescription>
+ Edit colors over the live panel. Export a shareable theme.json, save it here, or submit it to the registry.
+ </DialogDescription>
+ </DialogHeader>
+
+ <div className="theme-studio__top">
+ <label className="theme-studio__field">
+ <span>Name</span>
+ <input value={name} onChange={(e) => onNameChange(e.target.value)} />
+ </label>
+ <label className="theme-studio__field">
+ <span>Slug</span>
+ <input
+ value={slug}
+ onChange={(e) => { setSlug(slugify(e.target.value)); setSlugTouched(true); }}
+ />
+ </label>
+ <label className="theme-studio__field">
+ <span>Base</span>
+ <select value={base} onChange={(e) => setBase(e.target.value)}>
+ <option value="dark">dark</option>
+ <option value="light">light</option>
+ </select>
+ </label>
+ <label className="theme-studio__field">
+ <span>Start from</span>
+ <select defaultValue="" onChange={(e) => { startFrom(e.target.value); e.target.value = ''; }}>
+ <option value="" disabled>Choose…</option>
+ {availableThemes.map((t) => (
+ <option key={t.slug} value={t.slug}>{t.name || t.slug}</option>
+ ))}
+ </select>
+ </label>
+ </div>
+
+ <div className="theme-studio__modebar">
+ <div className="theme-studio__accent">
+ <span>Accent</span>
+ <input type="color" value={accent} onChange={(e) => setAccent(e.target.value)} />
+ </div>
+ <div className="theme-studio__modes">
+ <button
+ type="button"
+ className={editMode === 'dark' ? 'active' : ''}
+ onClick={() => setEditMode('dark')}
+ >Dark tokens</button>
+ <button
+ type="button"
+ className={editMode === 'light' ? 'active' : ''}
+ onClick={() => setEditMode('light')}
+ >Light tokens</button>
+ </div>
+ </div>
+
+ <div className="theme-studio__groups">
+ {Object.entries(TOKEN_GROUPS).map(([group, tokens]) => (
+ <div key={group} className="theme-studio__group">
+ <h4>{GROUP_LABELS[group]}</h4>
+ <div className="theme-studio__tokens">
+ {tokens.map((token) => {
+ const isColor = TOKEN_TYPE[token] === 'color';
+ const value = activeTokens[token] ?? '';
+ return (
+ <div key={token} className="theme-studio__token">
+ <label>{token}</label>
+ <div className="theme-studio__token-input">
+ {isColor && /^#([0-9a-fA-F]{6})$/.test(value) && (
+ <input
+ type="color"
+ value={value}
+ onChange={(e) => setToken(token, e.target.value)}
+ />
+ )}
+ <input
+ type="text"
+ value={value}
+ placeholder="unset"
+ onChange={(e) => setToken(token, e.target.value)}
+ />
+ </div>
+ </div>
+ );
+ })}
+ </div>
+ </div>
+ ))}
+ </div>
+
+ <div className="theme-studio__footer">
+ <Button variant="outline" size="sm" onClick={download}>
+ <Download size={14} /> Export theme.json
+ </Button>
+ <Button variant="outline" size="sm" onClick={submitToRegistry}>
+ <Github size={14} /> Submit to registry
+ </Button>
+ {isAdmin && (
+ <Button size="sm" onClick={saveToPanel} disabled={saving}>
+ <Save size={14} /> {saving ? 'Saving…' : 'Save to this panel'}
+ </Button>
+ )}
+ </div>
+ </DialogContent>
+ </Dialog>
+ );
+};
+
+export const ThemeStudioTrigger = ({ onClick }) => (
+ <Button variant="outline" size="sm" onClick={onClick}>
+ <Sparkles size={14} /> Create theme
+ </Button>
+);
+
+export default ThemeStudioModal;
diff --git a/frontend/src/contexts/ThemeContext.jsx b/frontend/src/contexts/ThemeContext.jsx
index f8a73f82..f950ae58 100644
--- a/frontend/src/contexts/ThemeContext.jsx
+++ b/frontend/src/contexts/ThemeContext.jsx
@@ -1,6 +1,7 @@
import { createContext, useContext, useState, useEffect, useCallback, useMemo } from 'react';
import { BUNDLED_THEMES, BUNDLED_THEME_MAP, DEFAULT_THEME_SLUG } from '../data/bundledThemes';
import { applySkin } from '../utils/applySkin';
+import api from '../services/api';
const ThemeContext = createContext(null);
@@ -101,13 +102,19 @@ export function ThemeProvider({ children }) {
return localStorage.getItem('accent_color') != null;
});
- // Selected skin slug (per-user, like dark/light). 'default' = stock look.
- const [skin, setSkinState] = useState(() => {
- return localStorage.getItem('skin') || DEFAULT_THEME_SLUG;
+ // The user's explicit skin choice (per-user, like dark/light), or null when
+ // they've never picked one — in which case the panel default is followed.
+ // 'default' means the user explicitly chose the stock look.
+ const [pickedSkin, setPickedSkinState] = useState(() => {
+ return localStorage.getItem('skin');
});
+ // The panel-wide default theme (fetched from the unauthenticated
+ // /themes/public/active). New users and the login/setup screens follow it.
+ const [panelDefaultTheme, setPanelDefaultTheme] = useState(null);
+
// Registry/imported themes merged on top of the bundled seeds at runtime
- // (populated in Phase 2 by fetching installed themes from the API).
+ // (populated by fetching installed themes from the API once authenticated).
const [installedThemes, setInstalledThemes] = useState({});
const [whiteLabel, setWhiteLabelState] = useState(() => {
@@ -136,6 +143,23 @@ export function ThemeProvider({ children }) {
return [...BUNDLED_THEMES, ...extras].map((t) => merged[t.slug] || t);
}, [installedThemes]);
+ // The slug actually in effect: the user's explicit pick, else the panel
+ // default, else the stock look.
+ const activeSlug = pickedSkin != null
+ ? pickedSkin
+ : (panelDefaultTheme?.slug || DEFAULT_THEME_SLUG);
+
+ // Resolve a slug to a theme object to skin with. 'default' (or unknown)
+ // resolves to null → applySkin clears overrides and the stock stylesheet
+ // shows. Falls back to the fetched panel-default object so a custom default
+ // paints the login screen even before its full record is loaded.
+ const resolveSkinTheme = useCallback((slug) => {
+ if (!slug || slug === DEFAULT_THEME_SLUG) return null;
+ if (themesMap[slug]) return themesMap[slug];
+ if (panelDefaultTheme && panelDefaultTheme.slug === slug) return panelDefaultTheme;
+ return null;
+ }, [themesMap, panelDefaultTheme]);
+
// Update the DOM attribute and resolved theme
const applyTheme = useCallback((newTheme) => {
document.documentElement.setAttribute('data-theme', newTheme);
@@ -164,10 +188,11 @@ export function ThemeProvider({ children }) {
localStorage.removeItem('accent_color');
}, []);
- // Public setter for the selected skin (per-user).
+ // Public setter for the selected skin (per-user). Persists an explicit
+ // choice; from now on this user no longer follows the panel default.
const setSkin = useCallback((slug) => {
const next = slug || DEFAULT_THEME_SLUG;
- setSkinState(next);
+ setPickedSkinState(next);
localStorage.setItem('skin', next);
}, []);
@@ -182,23 +207,41 @@ export function ThemeProvider({ children }) {
}, [resolvedTheme, workspaceAccent, hasCustomAccent, accentColor]);
const clearPreview = useCallback(() => {
- const skinTheme = skin !== DEFAULT_THEME_SLUG ? themesMap[skin] : null;
- const skinAccent = applySkin(skinTheme, resolvedTheme);
+ const skinAccent = applySkin(resolveSkinTheme(activeSlug), resolvedTheme);
applyAccentToDOM(
computeEffectiveAccent({ workspaceAccent, hasCustomAccent, accentColor, skinAccent }),
);
- }, [skin, themesMap, resolvedTheme, workspaceAccent, hasCustomAccent, accentColor]);
+ }, [resolveSkinTheme, activeSlug, resolvedTheme, workspaceAccent, hasCustomAccent, accentColor]);
- // Merge installed (registry/imported) themes into the selectable set.
+ // Replace the installed-theme set from an API listing (bundled dicts are
+ // harmless — the gallery de-dupes them against the seeds by slug). A replace
+ // (not merge) means an uninstalled theme disappears without a reload.
const registerInstalledThemes = useCallback((list) => {
if (!Array.isArray(list)) return;
- setInstalledThemes((prev) => {
- const next = { ...prev };
- for (const t of list) {
- if (t && t.slug) next[t.slug] = t;
- }
- return next;
- });
+ const map = {};
+ for (const t of list) {
+ if (t && t.slug) map[t.slug] = t;
+ }
+ setInstalledThemes(map);
+ }, []);
+
+ // Re-fetch installed themes (after an import/delete) and the panel default
+ // (after an admin changes it). Best-effort; failures leave state unchanged.
+ const refreshInstalledThemes = useCallback(async () => {
+ try {
+ const data = await api.getInstalledThemes();
+ if (data && Array.isArray(data.themes)) registerInstalledThemes(data.themes);
+ return data;
+ } catch {
+ return null;
+ }
+ }, [registerInstalledThemes]);
+
+ const refreshPanelDefault = useCallback(async () => {
+ try {
+ const data = await api.getPublicActiveTheme();
+ if (data && data.slug) setPanelDefaultTheme(data);
+ } catch { /* keep current */ }
}, []);
// Public setter for white label config (accepts partial updates)
@@ -229,18 +272,30 @@ export function ThemeProvider({ children }) {
applyTheme(theme);
}, [theme, applyTheme]);
+ // Fetch the panel default once (unauthenticated-safe) so new users and the
+ // login/setup screens follow it. Best-effort — a failure just leaves the
+ // stock look.
+ useEffect(() => {
+ let cancelled = false;
+ api.getPublicActiveTheme?.()
+ .then((data) => {
+ if (!cancelled && data && data.slug) setPanelDefaultTheme(data);
+ })
+ .catch(() => { /* stay on stock */ });
+ return () => { cancelled = true; };
+ }, []);
+
// Apply the active skin's tokens and the effective accent whenever anything
- // that feeds them changes. The 'default' slug means "no skin" — applySkin
- // is handed null so it clears any overrides and the stock stylesheet shows.
+ // that feeds them changes. A null resolution means "no skin" — applySkin
+ // clears any overrides and the stock stylesheet shows.
useEffect(() => {
- const skinTheme = skin !== DEFAULT_THEME_SLUG ? themesMap[skin] : null;
- const skinAccent = applySkin(skinTheme, resolvedTheme);
+ const skinAccent = applySkin(resolveSkinTheme(activeSlug), resolvedTheme);
applyAccentToDOM(
computeEffectiveAccent({ workspaceAccent, hasCustomAccent, accentColor, skinAccent }),
);
- }, [skin, resolvedTheme, accentColor, hasCustomAccent, workspaceAccent, themesMap]);
+ }, [activeSlug, resolveSkinTheme, resolvedTheme, accentColor, hasCustomAccent, workspaceAccent]);
- const activeTheme = skin !== DEFAULT_THEME_SLUG ? (themesMap[skin] || null) : null;
+ const activeTheme = resolveSkinTheme(activeSlug);
const value = {
theme, // Current setting: 'dark' | 'light' | 'system'
@@ -250,13 +305,17 @@ export function ThemeProvider({ children }) {
setAccentColor, // Function to change accent color
hasCustomAccent, // Whether the accent is an explicit user override
resetAccentColor,// Clear the explicit accent (fall back to skin/default)
- skin, // Selected skin slug ('default' = stock)
- setSkin, // Function to change the selected skin
- activeTheme, // The active skin's theme object (null for stock)
- availableThemes, // Selectable themes (bundled + installed)
+ skin: activeSlug, // Slug in effect (user pick, else panel default)
+ pickedSkin, // The user's explicit pick, or null (following default)
+ setSkin, // Function to change the selected skin
+ panelDefaultSlug: panelDefaultTheme?.slug || DEFAULT_THEME_SLUG,
+ activeTheme, // The active skin's theme object (null for stock)
+ availableThemes, // Selectable themes (bundled + installed)
previewSkin, // Temporarily apply a theme (hover preview)
clearPreview, // Restore the selected skin after a preview
- registerInstalledThemes, // Merge registry/imported themes into the set
+ registerInstalledThemes, // Replace the installed-theme set from a listing
+ refreshInstalledThemes, // Re-fetch installed themes (after import/delete)
+ refreshPanelDefault, // Re-fetch the panel default (after admin change)
whiteLabel, // White label config object
setWhiteLabel, // Function to update white label config
};
diff --git a/frontend/src/services/api/index.js b/frontend/src/services/api/index.js
index e338fd42..e5408bc1 100644
--- a/frontend/src/services/api/index.js
+++ b/frontend/src/services/api/index.js
@@ -44,6 +44,7 @@ import * as surveyMethods from './survey.js';
import * as dnsCutoverMethods from './dnsCutover.js';
import * as searchMethods from './search.js';
import * as testSandboxMethods from './testSandbox.js';
+import * as themeMethods from './themes.js';
class ApiService extends ApiClient {
constructor() {
@@ -95,6 +96,7 @@ class ApiService extends ApiClient {
dnsCutoverMethods,
searchMethods,
testSandboxMethods,
+ themeMethods,
];
for (const mod of modules) {
for (const [key, fn] of Object.entries(mod)) {
diff --git a/frontend/src/services/api/themes.js b/frontend/src/services/api/themes.js
new file mode 100644
index 00000000..dbf198ee
--- /dev/null
+++ b/frontend/src/services/api/themes.js
@@ -0,0 +1,60 @@
+// Themes platform API methods (plan 60).
+// A theme is data (a validated token map), so these are plain JSON calls — no
+// zip upload, no checksum dance.
+
+// All selectable themes (bundled seeds + installed) + the panel default slug.
+export async function getInstalledThemes() {
+ return this.request('/themes/installed');
+}
+
+// UNAUTHENTICATED pre-auth default — the login/setup screens call this before
+// anyone signs in to paint themselves with the panel default.
+export async function getPublicActiveTheme() {
+ return this.request('/themes/public/active');
+}
+
+// Import a theme from a parsed theme.json object (admin).
+export async function importTheme(theme, { source } = {}) {
+ const q = source === 'studio' ? '?source=studio' : '';
+ return this.request(`/themes/import${q}`, {
+ method: 'POST',
+ body: JSON.stringify(theme),
+ });
+}
+
+// Import a theme from an uploaded .json file (admin).
+export async function importThemeFile(file) {
+ const form = new FormData();
+ form.append('file', file);
+ return this.request('/themes/import', { method: 'POST', body: form });
+}
+
+// Uninstall an installed theme by slug (admin). Bundled seeds can't be removed.
+export async function deleteTheme(slug) {
+ return this.request(`/themes/${encodeURIComponent(slug)}`, { method: 'DELETE' });
+}
+
+// The panel-wide default theme slug.
+export async function getDefaultTheme() {
+ return this.request('/themes/default');
+}
+
+// Set the panel-wide default theme (admin).
+export async function setDefaultTheme(slug) {
+ return this.request('/themes/default', {
+ method: 'POST',
+ body: JSON.stringify({ slug }),
+ });
+}
+
+// Browse the remote theme registry (with live install state). Offline-tolerant.
+export async function getThemeRegistry() {
+ return this.request('/themes/registry');
+}
+
+// Install a theme from the registry by slug (admin).
+export async function installRegistryTheme(slug) {
+ return this.request(`/themes/registry/${encodeURIComponent(slug)}/install`, {
+ method: 'POST',
+ });
+}
diff --git a/frontend/src/styles/pages/_settings.scss b/frontend/src/styles/pages/_settings.scss
index 9bb5e556..3b62a676 100644
--- a/frontend/src/styles/pages/_settings.scss
+++ b/frontend/src/styles/pages/_settings.scss
@@ -1351,6 +1351,23 @@
// THEME GALLERY (plan 60 — community themes)
// ============================================
+.theme-gallery-header {
+ display: flex;
+ align-items: flex-start;
+ justify-content: space-between;
+ gap: $space-3;
+ margin-bottom: $space-3;
+
+ h3 { margin-bottom: 2px; }
+ p { margin: 0; }
+}
+
+.theme-gallery-actions {
+ display: flex;
+ flex-shrink: 0;
+ gap: $space-2;
+}
+
.theme-gallery {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(180px, 1fr));
@@ -1425,6 +1442,14 @@
color: var(--text-dim);
}
+ &__footer {
+ display: flex;
+ flex-wrap: wrap;
+ align-items: center;
+ gap: $space-2;
+ min-height: 16px;
+ }
+
&__applied {
display: inline-flex;
align-items: center;
@@ -1433,6 +1458,312 @@
font-weight: $font-weight-medium;
color: var(--accent-primary);
}
+
+ &__default {
+ display: inline-flex;
+ align-items: center;
+ gap: 4px;
+ font-size: $font-size-xs;
+ font-weight: $font-weight-medium;
+ color: var(--amber);
+ }
+
+ &__admin {
+ display: flex;
+ flex-wrap: wrap;
+ gap: $space-2;
+ padding-top: $space-2;
+ border-top: 1px solid var(--border-soft);
+ }
+
+ &__admin-btn {
+ display: inline-flex;
+ align-items: center;
+ gap: 4px;
+ padding: 3px 8px;
+ font-size: $font-size-xs;
+ font-weight: $font-weight-medium;
+ color: var(--text-dim);
+ background: transparent;
+ border: 1px solid var(--border);
+ border-radius: $radius-sm;
+ cursor: pointer;
+ transition: all $transition-fast;
+
+ &:hover:not(:disabled) {
+ color: var(--text);
+ border-color: var(--border-strong);
+ }
+
+ &:disabled { opacity: 0.5; cursor: default; }
+
+ &--danger:hover:not(:disabled) {
+ color: var(--red);
+ border-color: var(--red);
+ }
+ }
+}
+
+// ---- Browse-themes modal (registry) ----
+.theme-browse__state {
+ display: flex;
+ align-items: center;
+ gap: $space-2;
+ padding: $space-5 $space-3;
+ color: var(--text-dim);
+ font-size: $font-size-sm;
+
+ .spin { animation: theme-spin 1s linear infinite; }
+}
+
+.theme-browse__grid {
+ display: grid;
+ grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+ gap: $space-3;
+ max-height: 60vh;
+ overflow-y: auto;
+ padding: 2px;
+}
+
+.theme-browse__card {
+ display: flex;
+ flex-direction: column;
+ gap: $space-2;
+ padding: $space-3;
+ background: var(--surface-2);
+ border: 1px solid var(--border);
+ border-radius: $radius-lg;
+
+ .theme-browse__swatches {
+ display: flex;
+ height: 40px;
+ border-radius: $radius-md;
+ overflow: hidden;
+ border: 1px solid var(--border-soft);
+
+ span { flex: 1; }
+ }
+
+ .theme-browse__meta {
+ display: flex;
+ align-items: baseline;
+ justify-content: space-between;
+ gap: $space-2;
+ }
+
+ .theme-browse__name {
+ font-size: $font-size-sm;
+ font-weight: $font-weight-semibold;
+ color: var(--text);
+ }
+
+ .theme-browse__author {
+ font-size: $font-size-xs;
+ color: var(--text-faint);
+ }
+
+ .theme-browse__desc {
+ margin: 0;
+ font-size: $font-size-xs;
+ line-height: 1.4;
+ color: var(--text-dim);
+ }
+
+ .theme-browse__installed {
+ display: inline-flex;
+ align-items: center;
+ gap: 4px;
+ font-size: $font-size-xs;
+ font-weight: $font-weight-medium;
+ color: var(--green);
+ }
+
+ .theme-browse__install {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ gap: 5px;
+ padding: 5px 10px;
+ font-size: $font-size-xs;
+ font-weight: $font-weight-medium;
+ color: var(--text);
+ background: var(--surface-3);
+ border: 1px solid var(--border);
+ border-radius: $radius-sm;
+ cursor: pointer;
+ transition: all $transition-fast;
+
+ &:hover:not(:disabled) { border-color: var(--accent-primary); color: var(--accent-primary); }
+ &:disabled { opacity: 0.6; cursor: default; }
+
+ .spin { animation: theme-spin 1s linear infinite; }
+ }
+}
+
+@keyframes theme-spin {
+ to { transform: rotate(360deg); }
+}
+
+// ---- Theme Studio ----
+.theme-studio {
+ max-width: 720px;
+
+ &__top {
+ display: grid;
+ grid-template-columns: repeat(2, 1fr);
+ gap: $space-3;
+
+ @media (max-width: $breakpoint-md) {
+ grid-template-columns: 1fr;
+ }
+ }
+
+ &__field {
+ display: flex;
+ flex-direction: column;
+ gap: 4px;
+
+ span {
+ font-size: $font-size-xs;
+ font-weight: $font-weight-medium;
+ color: var(--text-dim);
+ }
+
+ input, select {
+ padding: 6px 10px;
+ font-size: $font-size-sm;
+ color: var(--text);
+ background: var(--surface);
+ border: 1px solid var(--border);
+ border-radius: $radius-sm;
+ }
+ }
+
+ &__modebar {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: $space-3;
+ margin-top: $space-3;
+ padding-top: $space-3;
+ border-top: 1px solid var(--border-soft);
+ }
+
+ &__accent {
+ display: flex;
+ align-items: center;
+ gap: $space-2;
+ font-size: $font-size-sm;
+ color: var(--text-dim);
+
+ input[type="color"] {
+ width: 34px;
+ height: 28px;
+ padding: 0;
+ border: 1px solid var(--border);
+ border-radius: $radius-sm;
+ background: transparent;
+ cursor: pointer;
+ }
+ }
+
+ &__modes {
+ display: inline-flex;
+ border: 1px solid var(--border);
+ border-radius: $radius-sm;
+ overflow: hidden;
+
+ button {
+ padding: 5px 12px;
+ font-size: $font-size-xs;
+ font-weight: $font-weight-medium;
+ color: var(--text-dim);
+ background: transparent;
+ border: none;
+ cursor: pointer;
+
+ &.active { background: var(--accent-bg); color: var(--accent-primary); }
+ }
+ }
+
+ &__groups {
+ margin-top: $space-3;
+ max-height: 48vh;
+ overflow-y: auto;
+ display: flex;
+ flex-direction: column;
+ gap: $space-4;
+ padding-right: 2px;
+ }
+
+ &__group h4 {
+ margin: 0 0 $space-2;
+ font-size: $font-size-xs;
+ text-transform: uppercase;
+ letter-spacing: 0.05em;
+ color: var(--text-faint);
+ }
+
+ &__tokens {
+ display: grid;
+ grid-template-columns: repeat(2, 1fr);
+ gap: $space-2;
+
+ @media (max-width: $breakpoint-md) {
+ grid-template-columns: 1fr;
+ }
+ }
+
+ &__token {
+ display: flex;
+ flex-direction: column;
+ gap: 3px;
+
+ label {
+ font-family: $font-mono;
+ font-size: 11px;
+ color: var(--text-dim);
+ }
+ }
+
+ &__token-input {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+
+ input[type="color"] {
+ width: 30px;
+ height: 26px;
+ flex-shrink: 0;
+ padding: 0;
+ border: 1px solid var(--border);
+ border-radius: $radius-sm;
+ background: transparent;
+ cursor: pointer;
+ }
+
+ input[type="text"] {
+ flex: 1;
+ min-width: 0;
+ padding: 5px 8px;
+ font-family: $font-mono;
+ font-size: 12px;
+ color: var(--text);
+ background: var(--surface);
+ border: 1px solid var(--border);
+ border-radius: $radius-sm;
+ }
+ }
+
+ &__footer {
+ display: flex;
+ flex-wrap: wrap;
+ justify-content: flex-end;
+ gap: $space-2;
+ margin-top: $space-4;
+ padding-top: $space-3;
+ border-top: 1px solid var(--border-soft);
+ }
}
// ============================================