feat: visual identity, theme toggle, custom CSS, loading states (M4)

Grounds the visual design in the product's own subject matter (vital-
signs monitoring) rather than generic dark-mode defaults: a signature
"pulse" green tied to healthy status (the accent color and the "up"
status color are the same hue - a steady green pulse reads as
healthy, same convention as a cardiac monitor), a small ECG-trace
brand mark, and a restrained pulsing-glow animation on healthy status
dots (prefers-reduced-motion respected) as the one deliberate motion
touch. Typography moves off the bare system-ui stack: IBM Plex Sans
for UI text, IBM Plex Mono with tabular numerals for metric values
(CPU/mem/uptime/latency), Space Grotesk used once for the wordmark -
chosen partly for IBM Plex's own systems-monitoring heritage.

Functional additions:
- Light/dark toggle, independent of config.yml's theme.mode, persisted
  to localStorage with a blocking inline script to avoid a flash of
  the wrong theme on load; auto mode now genuinely follows
  prefers-color-scheme instead of hardcoding dark.
- theme.customCssPath support via a new route handler that serves a
  user-mounted CSS file at runtime (can't be a build-time import,
  hence the targeted no-css-tags lint suppression), with a path-
  traversal guard since it's still reading from disk on every request.
- Loading-skeleton state for widgets awaiting their first WebSocket
  result, distinct from both the error state and genuine no-data.

Verified visually in Chrome: theme toggle switches instantly in both
directions, a live docker widget's status dot and monospace metrics
render correctly in both palettes, and config hot-reload still adds a
new widget without a page refresh.

app/api/theme/custom-css/route.ts

@@ -0,0 +1,34 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { configStore } from "@/lib/config/loader";
+
+export const dynamic = "force-dynamic";
+
+const CONFIG_DIR = path.join(process.cwd(), "config");
+
+export async function GET(): Promise<Response> {
+  let customCssPath: string | undefined;
+  try {
+    customCssPath = configStore.get().theme.customCssPath;
+  } catch {
+    return new Response("", { status: 204 });
+  }
+
+  if (!customCssPath) {
+    return new Response("", { status: 204 });
+  }
+
+  const resolved = path.normalize(path.join(CONFIG_DIR, customCssPath));
+  if (!resolved.startsWith(CONFIG_DIR + path.sep)) {
+    return new Response("", { status: 204 });
+  }
+
+  try {
+    const css = await readFile(resolved, "utf-8");
+    return new Response(css, {
+      headers: { "Content-Type": "text/css; charset=utf-8", "Cache-Control": "no-cache" },
+    });
+  } catch {
+    return new Response("", { status: 204 });
+  }
+}

app/globals.css

@@ -1,32 +1,47 @@
 @import "tailwindcss";
 
 :root {
-  --pn-bg: #0b0d12;
-  --pn-surface: #12151c;
-  --pn-surface-raised: #171b24;
-  --pn-border: #242938;
-  --pn-fg: #e6e8ee;
-  --pn-fg-muted: #8a90a2;
-  --pn-accent: #38bdf8;
+  --pn-bg: #0a0e13;
+  --pn-surface: #10151c;
+  --pn-surface-raised: #161d27;
+  --pn-border: #232b38;
+  --pn-fg: #e8ecf1;
+  --pn-fg-muted: #7c8798;
+  --pn-accent: #3ee8a8;
   --pn-radius: 0.75rem;
-  --pn-status-up: #34d399;
-  --pn-status-down: #f87171;
-  --pn-status-degraded: #fbbf24;
+  --pn-status-up: #3ee8a8;
+  --pn-status-down: #ff5f6d;
+  --pn-status-degraded: #ffb84c;
 }
 
 :root[data-theme="light"] {
-  --pn-bg: #f5f6f8;
+  --pn-bg: #f6f7f5;
   --pn-surface: #ffffff;
-  --pn-surface-raised: #f0f1f4;
-  --pn-border: #e2e4ea;
-  --pn-fg: #14161c;
-  --pn-fg-muted: #666b7a;
-  --pn-accent: #0284c7;
-  --pn-status-up: #059669;
+  --pn-surface-raised: #eef1ef;
+  --pn-border: #dde1de;
+  --pn-fg: #12181a;
+  --pn-fg-muted: #5c6b66;
+  --pn-accent: #0e9f6e;
+  --pn-status-up: #0e9f6e;
   --pn-status-down: #dc2626;
   --pn-status-degraded: #d97706;
 }
 
+@media (prefers-color-scheme: light) {
+  :root:not([data-theme]) {
+    --pn-bg: #f6f7f5;
+    --pn-surface: #ffffff;
+    --pn-surface-raised: #eef1ef;
+    --pn-border: #dde1de;
+    --pn-fg: #12181a;
+    --pn-fg-muted: #5c6b66;
+    --pn-accent: #0e9f6e;
+    --pn-status-up: #0e9f6e;
+    --pn-status-down: #dc2626;
+    --pn-status-degraded: #d97706;
+  }
+}
+
 @theme inline {
   --color-bg: var(--pn-bg);
   --color-surface: var(--pn-surface);
@@ -39,11 +54,32 @@
   --color-status-down: var(--pn-status-down);
   --color-status-degraded: var(--pn-status-degraded);
   --radius-widget: var(--pn-radius);
+  --font-sans: var(--font-plex-sans);
+  --font-mono: var(--font-plex-mono);
+  --font-display: var(--font-space-grotesk);
 }
 
 body {
   background: var(--pn-bg);
   color: var(--pn-fg);
-  font-family:
-    ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+}
+
+@keyframes pulse-glow {
+  0%,
+  100% {
+    box-shadow: 0 0 0 0 color-mix(in srgb, var(--pn-status-up) 55%, transparent);
+  }
+  50% {
+    box-shadow: 0 0 0 4px color-mix(in srgb, var(--pn-status-up) 0%, transparent);
+  }
+}
+
+.status-pulse {
+  animation: pulse-glow 2s ease-in-out infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .status-pulse {
+    animation: none;
+  }
 }

app/layout.tsx

@@ -1,31 +1,67 @@
 import type { Metadata } from "next";
+import { IBM_Plex_Sans, IBM_Plex_Mono, Space_Grotesk } from "next/font/google";
 import "./globals.css";
 import { configStore } from "@/lib/config/loader";
 import { ThemeStyleInjector } from "@/components/layout/ThemeStyleInjector";
 
+const plexSans = IBM_Plex_Sans({
+  variable: "--font-plex-sans",
+  subsets: ["latin"],
+  weight: ["400", "500", "600"],
+});
+
+const plexMono = IBM_Plex_Mono({
+  variable: "--font-plex-mono",
+  subsets: ["latin"],
+  weight: ["400", "500"],
+});
+
+const spaceGrotesk = Space_Grotesk({
+  variable: "--font-space-grotesk",
+  subsets: ["latin"],
+  weight: ["600"],
+});
+
 export const metadata: Metadata = {
   title: "PulseNode",
   description: "Self-hosted infrastructure dashboard",
 };
 
+const THEME_STORAGE_KEY = "pulsenode-theme";
+
+const themeInitScript = `try{var t=localStorage.getItem(${JSON.stringify(THEME_STORAGE_KEY)});if(t==="dark"||t==="light"){document.documentElement.dataset.theme=t;}}catch(e){}`;
+
 export default function RootLayout({ children }: LayoutProps<"/">) {
-  let mode: "dark" | "light" = "dark";
+  let mode: "dark" | "light" | "auto" = "dark";
   let variables: Record<string, string> = {};
+  let customCssPath: string | undefined;
 
   try {
     const config = configStore.get();
-    mode = config.theme.mode === "light" ? "light" : "dark";
+    mode = config.theme.mode;
     variables = config.theme.variables;
+    customCssPath = config.theme.customCssPath;
   } catch {
     // page.tsx surfaces the actual config error; layout falls back to defaults
   }
 
   return (
-    <html lang="en" data-theme={mode} className="h-full">
+    <html
+      lang="en"
+      {...(mode !== "auto" ? { "data-theme": mode } : {})}
+      className={`h-full ${plexSans.variable} ${plexMono.variable} ${spaceGrotesk.variable}`}
+    >
       <head>
+        <script dangerouslySetInnerHTML={{ __html: themeInitScript }} />
         <ThemeStyleInjector variables={variables} />
+        {customCssPath && (
+          // Served at runtime from a user-mounted file via a route handler;
+          // can't be a build-time CSS import.
+          // eslint-disable-next-line @next/next/no-css-tags
+          <link rel="stylesheet" href="/api/theme/custom-css" />
+        )}
       </head>
-      <body className="min-h-full antialiased">{children}</body>
+      <body className="min-h-full font-sans antialiased">{children}</body>
     </html>
   );
 }

components/layout/Dashboard.tsx

@@ -3,14 +3,22 @@
 import type { Config } from "@/lib/config/schema";
 import { useConfigSubscription } from "@/lib/ws/client";
 import { GroupSection } from "./GroupSection";
+import { ThemeToggle } from "./ThemeToggle";
+import { PulseMark } from "./PulseMark";
 
 export function Dashboard({ config: initialConfig }: { config: Config }) {
   const config = useConfigSubscription(initialConfig);
 
   return (
     <main className="mx-auto flex max-w-6xl flex-col gap-8 px-6 py-10">
-      <header className="flex items-center justify-between">
-        <h1 className="text-lg font-semibold text-fg">{config.settings.title}</h1>
+      <header className="flex items-center justify-between gap-4">
+        <div className="flex items-center gap-3">
+          <PulseMark />
+          <h1 className="font-display text-lg font-semibold tracking-tight text-fg">
+            {config.settings.title}
+          </h1>
+        </div>
+        <ThemeToggle />
       </header>
       {config.groups.map((group, groupIndex) => (
         <GroupSection key={group.name} group={group} groupIndex={groupIndex} />

components/layout/PulseMark.tsx

@@ -0,0 +1,21 @@
+export function PulseMark() {
+  return (
+    <svg
+      width="30"
+      height="16"
+      viewBox="0 0 60 24"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      aria-hidden="true"
+      className="text-accent"
+    >
+      <path
+        d="M0 12H11L15 5L20 19L24 12H33L37 8L41 12H60"
+        stroke="currentColor"
+        strokeWidth="2.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}

components/layout/ThemeToggle.tsx

@@ -0,0 +1,50 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+const STORAGE_KEY = "pulsenode-theme";
+
+export function ThemeToggle() {
+  const [theme, setTheme] = useState<"dark" | "light" | null>(null);
+
+  useEffect(() => {
+    // One-time read of browser-only state (DOM attribute set by the anti-FOUC
+    // inline script, or the OS color-scheme preference) to resolve the theme
+    // React couldn't know during SSR. Not a case of syncing to external state
+    // that changes over time, so a single setState here is the right call.
+    const attr = document.documentElement.dataset.theme;
+    if (attr === "light" || attr === "dark") {
+      // eslint-disable-next-line react-hooks/set-state-in-effect
+      setTheme(attr);
+      return;
+    }
+    const prefersLight = window.matchMedia("(prefers-color-scheme: light)").matches;
+    setTheme(prefersLight ? "light" : "dark");
+  }, []);
+
+  function toggle() {
+    const next = theme === "light" ? "dark" : "light";
+    setTheme(next);
+    document.documentElement.dataset.theme = next;
+    try {
+      localStorage.setItem(STORAGE_KEY, next);
+    } catch {
+      // private browsing or storage disabled; toggle still works for this session
+    }
+  }
+
+  if (theme === null) {
+    return <div className="h-7 w-16 rounded-[var(--radius-widget)] border border-border bg-surface" />;
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={toggle}
+      className="rounded-[var(--radius-widget)] border border-border bg-surface px-3 py-1.5 text-xs text-fg-muted transition-colors hover:text-fg"
+      aria-label="Toggle color theme"
+    >
+      {theme === "light" ? "Light" : "Dark"}
+    </button>
+  );
+}

components/widgets/Skeleton.tsx

@@ -0,0 +1,13 @@
+export function SkeletonLines({ count = 2 }: { count?: number }) {
+  return (
+    <div className="flex flex-col gap-1.5">
+      {Array.from({ length: count }, (_, index) => (
+        <div
+          key={index}
+          className="h-3 animate-pulse rounded bg-surface-raised"
+          style={{ width: `${70 - index * 15}%` }}
+        />
+      ))}
+    </div>
+  );
+}

components/widgets/StatusDot.tsx

@@ -14,12 +14,17 @@ function resolveColorClass(status?: Props["status"], health?: Props["health"]):
   return "bg-status-down";
 }
 
+function isHealthy(status?: Props["status"], health?: Props["health"]): boolean {
+  return status === "running" && health !== "unhealthy" && health !== "starting";
+}
+
 export function StatusDot({ status, health }: Props) {
   const label = status ? `${status}${health && health !== "none" ? ` (${health})` : ""}` : "unknown";
+  const pulse = isHealthy(status, health) ? "status-pulse" : "";
 
   return (
     <span
-      className={`h-2.5 w-2.5 shrink-0 rounded-full ${resolveColorClass(status, health)}`}
+      className={`h-2.5 w-2.5 shrink-0 rounded-full ${resolveColorClass(status, health)} ${pulse}`}
       title={label}
     />
   );

components/widgets/database/Widget.tsx

@@ -26,7 +26,9 @@ export function DatabaseWidget({ widget, widgetId }: { widget: DatabaseWidget; w
       <span className="text-xs text-fg-muted">{ENGINE_LABEL[widget.engine]}</span>
       {errorMessage && <span className="text-xs text-status-down">{errorMessage}</span>}
       {data?.uptimeSeconds != null && (
-        <span className="text-xs text-fg-muted">Uptime: {formatUptime(data.uptimeSeconds)}</span>
+        <span className="text-xs text-fg-muted">
+          Uptime: <span className="font-mono tabular-nums text-fg">{formatUptime(data.uptimeSeconds)}</span>
+        </span>
       )}
     </div>
   );

components/widgets/docker/Widget.tsx

@@ -3,6 +3,7 @@
 import type { Widget } from "@/lib/config/schema";
 import { useWidgetSubscription } from "@/lib/ws/client";
 import { StatusDot } from "@/components/widgets/StatusDot";
+import { SkeletonLines } from "@/components/widgets/Skeleton";
 import { formatBytes, formatUptime } from "@/lib/format";
 
 type DockerWidget = Extract<Widget, { type: "docker" }>;
@@ -30,17 +31,33 @@ export function DockerWidget({ widget, widgetId }: { widget: DockerWidget; widge
         <StatusDot status={data?.status} health={data?.health} />
       </div>
       {errorMessage && <span className="text-xs text-status-down">{errorMessage}</span>}
+      {!result && !errorMessage && <SkeletonLines />}
       {data && (
         <dl className="flex flex-col gap-1 text-xs text-fg-muted">
-          {data.uptimeSeconds !== null && <div>Uptime: {formatUptime(data.uptimeSeconds)}</div>}
-          {widget.showStats && data.cpuPercent !== null && <div>CPU: {data.cpuPercent.toFixed(1)}%</div>}
-          {widget.showStats && data.memUsageBytes !== null && (
+          {data.uptimeSeconds !== null && (
             <div>
-              Mem: {formatBytes(data.memUsageBytes)}
-              {data.memLimitBytes ? ` / ${formatBytes(data.memLimitBytes)}` : ""}
+              Uptime: <span className="font-mono tabular-nums text-fg">{formatUptime(data.uptimeSeconds)}</span>
+            </div>
+          )}
+          {widget.showStats && data.cpuPercent !== null && (
+            <div>
+              CPU: <span className="font-mono tabular-nums text-fg">{data.cpuPercent.toFixed(1)}%</span>
+            </div>
+          )}
+          {widget.showStats && data.memUsageBytes !== null && (
+            <div>
+              Mem:{" "}
+              <span className="font-mono tabular-nums text-fg">
+                {formatBytes(data.memUsageBytes)}
+                {data.memLimitBytes ? ` / ${formatBytes(data.memLimitBytes)}` : ""}
+              </span>
+            </div>
+          )}
+          {data.restartCount > 0 && (
+            <div>
+              Restarts: <span className="font-mono tabular-nums text-fg">{data.restartCount}</span>
             </div>
           )}
-          {data.restartCount > 0 && <div>Restarts: {data.restartCount}</div>}
         </dl>
       )}
     </div>

components/widgets/http/Widget.tsx

@@ -2,6 +2,7 @@
 
 import type { Widget } from "@/lib/config/schema";
 import { useWidgetSubscription } from "@/lib/ws/client";
+import { SkeletonLines } from "@/components/widgets/Skeleton";
 
 type HttpWidget = Extract<Widget, { type: "http" }>;
 
@@ -15,21 +16,27 @@ export function HttpWidget({ widget, widgetId }: { widget: HttpWidget; widgetId:
   const result = useWidgetSubscription(widgetId);
   const data = result?.type === "http" ? result.data : null;
   const errorMessage = result?.type === "error" ? result.message : null;
+  const pulse = data?.up ? "status-pulse" : "";
 
   return (
     <div className="flex flex-col gap-2 rounded-[var(--radius-widget)] border border-border bg-surface p-4">
       <div className="flex items-center justify-between gap-2">
         <span className="text-sm font-medium text-fg">{widget.name}</span>
         <span
-          className={`h-2.5 w-2.5 shrink-0 rounded-full ${statusColor(data?.up, data?.consecutiveFailures ?? 0)}`}
+          className={`h-2.5 w-2.5 shrink-0 rounded-full ${statusColor(data?.up, data?.consecutiveFailures ?? 0)} ${pulse}`}
           title={data ? (data.up ? "up" : `down (${data.consecutiveFailures} checks failed)`) : "unknown"}
         />
       </div>
       {errorMessage && <span className="text-xs text-status-down">{errorMessage}</span>}
+      {!result && !errorMessage && <SkeletonLines />}
       {data && (
         <dl className="flex flex-col gap-1 text-xs text-fg-muted">
-          <div>Status: {data.statusCode ?? "—"}</div>
-          <div>Latency: {data.latencyMs}ms</div>
+          <div>
+            Status: <span className="font-mono tabular-nums text-fg">{data.statusCode ?? "—"}</span>
+          </div>
+          <div>
+            Latency: <span className="font-mono tabular-nums text-fg">{data.latencyMs}ms</span>
+          </div>
           {!data.up && data.error && <div className="text-status-down">{data.error}</div>}
         </dl>
       )}

components/widgets/system/Widget.tsx

@@ -2,6 +2,7 @@
 
 import type { Widget } from "@/lib/config/schema";
 import { useWidgetSubscription } from "@/lib/ws/client";
+import { SkeletonLines } from "@/components/widgets/Skeleton";
 import { formatBytes } from "@/lib/format";
 
 type SystemWidget = Extract<Widget, { type: "system" }>;
@@ -15,13 +16,10 @@ function UsageBar({ label, percent, detail }: { label: string; percent: number;
     <div className="flex flex-col gap-1">
       <div className="flex items-center justify-between text-xs text-fg-muted">
         <span>{label}</span>
-        <span>{detail}</span>
+        <span className="font-mono tabular-nums text-fg">{detail}</span>
       </div>
       <div className="h-1.5 w-full overflow-hidden rounded-full bg-surface-raised">
-        <div
-          className="h-full rounded-full bg-accent"
-          style={{ width: `${percent}%` }}
-        />
+        <div className="h-full rounded-full bg-accent" style={{ width: `${percent}%` }} />
       </div>
     </div>
   );
@@ -36,6 +34,7 @@ export function SystemWidget({ widget, widgetId }: { widget: SystemWidget; widge
     <div className="flex flex-col gap-3 rounded-[var(--radius-widget)] border border-border bg-surface p-4 sm:col-span-2">
       <span className="text-sm font-medium text-fg">{widget.name}</span>
       {errorMessage && <span className="text-xs text-status-down">{errorMessage}</span>}
+      {!result && !errorMessage && <SkeletonLines count={3} />}
       {data && (
         <div className="flex flex-col gap-2">
           <UsageBar label="CPU" percent={data.cpuPercent} detail={`${data.cpuPercent.toFixed(1)}%`} />
@@ -51,7 +50,7 @@ export function SystemWidget({ widget, widgetId }: { widget: SystemWidget; widge
           />
           <div className="flex items-center justify-between text-xs text-fg-muted">
             <span>Network</span>
-            <span>
+            <span className="font-mono tabular-nums text-fg">
               ↓ {formatBytes(data.netRxBytesPerSec)}/s · ↑ {formatBytes(data.netTxBytesPerSec)}/s
             </span>
           </div>

components/widgets/traefik/Widget.tsx

@@ -2,6 +2,7 @@
 
 import type { Widget } from "@/lib/config/schema";
 import { useWidgetSubscription } from "@/lib/ws/client";
+import { SkeletonLines } from "@/components/widgets/Skeleton";
 
 type TraefikWidget = Extract<Widget, { type: "traefik" }>;
 
@@ -15,12 +16,13 @@ export function TraefikWidget({ widget, widgetId }: { widget: TraefikWidget; wid
       <div className="flex items-center justify-between">
         <span className="text-sm font-medium text-fg">{widget.name}</span>
         {data && (
-          <span className="text-xs text-fg-muted">
+          <span className="font-mono text-xs tabular-nums text-fg-muted">
             {data.entrypoints.map((ep) => ep.address).join(" · ") || `${data.entrypoints.length} entrypoints`}
           </span>
         )}
       </div>
       {errorMessage && <span className="text-xs text-status-down">{errorMessage}</span>}
+      {!result && !errorMessage && <SkeletonLines count={3} />}
       {data && (
         <div className="flex flex-col gap-1">
           {data.routers.map((router) => (
@@ -38,7 +40,9 @@ export function TraefikWidget({ widget, widgetId }: { widget: TraefikWidget; wid
               </span>
             </div>
           ))}
-          <span className="pt-1 text-xs text-fg-muted">{data.middlewaresCount} middlewares</span>
+          <span className="pt-1 text-xs text-fg-muted">
+            <span className="font-mono tabular-nums">{data.middlewaresCount}</span> middlewares
+          </span>
         </div>
       )}
     </div>