From 76397802d00d916531c32f0cb45339f894c820d0 Mon Sep 17 00:00:00 2001
From: merencia <lucas.merencia@gmail.com>
Date: Fri, 3 Jul 2026 20:02:01 -0300
Subject: [PATCH 1/7] feat(dashboard): sync design tokens and add Card + Badge
 primitives

syncs the sidequest.js design system: ships the tokens (colors, typography, spacing, radii, fonts) plus the .sq-* base layer as @sidequest/dashboard/ui/styles.css, and drops tailwind from the ui in favor of the design system's css-variable tokens with inline-styled components.

adds the first two primitives, Card and Badge, ported faithfully from the design system, each at 100% test coverage with storybook stories rendered on the dark product surface.
---
 eslint.config.js                              |   1 +
 packages/dashboard/.storybook/main.ts         |   5 -
 packages/dashboard/.storybook/preview.ts      |   6 -
 packages/dashboard/.storybook/preview.tsx     |  14 ++
 packages/dashboard/package.json               |   4 +-
 packages/dashboard/src/ui/Badge.stories.tsx   |  41 ++++
 packages/dashboard/src/ui/Badge.test.tsx      |  39 +++
 packages/dashboard/src/ui/Badge.tsx           |  73 ++++++
 packages/dashboard/src/ui/Card.stories.tsx    |  22 +-
 packages/dashboard/src/ui/Card.test.tsx       |  56 +++--
 packages/dashboard/src/ui/Card.tsx            |  84 +++++--
 packages/dashboard/src/ui/index.ts            |   4 +-
 packages/dashboard/src/ui/styles.css          |  26 +-
 packages/dashboard/src/ui/tokens/base.css     |  64 +++++
 packages/dashboard/src/ui/tokens/colors.css   | 137 +++++++++++
 packages/dashboard/src/ui/tokens/fonts.css    |   9 +
 packages/dashboard/src/ui/tokens/radii.css    |  32 +++
 packages/dashboard/src/ui/tokens/spacing.css  |  24 ++
 .../dashboard/src/ui/tokens/typography.css    |  43 ++++
 packages/dashboard/vite.lib.config.ts         |  14 ++
 yarn.lock                                     | 225 +-----------------
 21 files changed, 624 insertions(+), 299 deletions(-)
 delete mode 100644 packages/dashboard/.storybook/preview.ts
 create mode 100644 packages/dashboard/.storybook/preview.tsx
 create mode 100644 packages/dashboard/src/ui/Badge.stories.tsx
 create mode 100644 packages/dashboard/src/ui/Badge.test.tsx
 create mode 100644 packages/dashboard/src/ui/Badge.tsx
 create mode 100644 packages/dashboard/src/ui/tokens/base.css
 create mode 100644 packages/dashboard/src/ui/tokens/colors.css
 create mode 100644 packages/dashboard/src/ui/tokens/fonts.css
 create mode 100644 packages/dashboard/src/ui/tokens/radii.css
 create mode 100644 packages/dashboard/src/ui/tokens/spacing.css
 create mode 100644 packages/dashboard/src/ui/tokens/typography.css

diff --git a/eslint.config.js b/eslint.config.js
index 76dedb6..f403d0e 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -18,6 +18,7 @@ export default tseslint.config(
       "**/public/**",
       "**/views/**",
       "**/migrations/**",
+      "**/storybook-static/**",
       "packages/docs/.vitepress/cache/**",
       "packages/dashboard/vite.lib.config.ts",
       "packages/dashboard/vitest.setup.ts",
diff --git a/packages/dashboard/.storybook/main.ts b/packages/dashboard/.storybook/main.ts
index ddc89f5..8c96dc7 100644
--- a/packages/dashboard/.storybook/main.ts
+++ b/packages/dashboard/.storybook/main.ts
@@ -1,14 +1,9 @@
 import type { StorybookConfig } from "@storybook/react-vite";
-import tailwindcss from "@tailwindcss/vite";
 
 const config: StorybookConfig = {
   stories: ["../src/ui/**/*.stories.@(ts|tsx)"],
   framework: { name: "@storybook/react-vite", options: {} },
   core: { disableTelemetry: true },
-  viteFinal: async (cfg) => {
-    const { mergeConfig } = await import("vite");
-    return mergeConfig(cfg, { plugins: [tailwindcss()] });
-  },
 };
 
 export default config;
diff --git a/packages/dashboard/.storybook/preview.ts b/packages/dashboard/.storybook/preview.ts
deleted file mode 100644
index a39165c..0000000
--- a/packages/dashboard/.storybook/preview.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-import type { Preview } from "@storybook/react-vite";
-import "../src/ui/styles.css";
-
-const preview: Preview = {};
-
-export default preview;
diff --git a/packages/dashboard/.storybook/preview.tsx b/packages/dashboard/.storybook/preview.tsx
new file mode 100644
index 0000000..5e18b62
--- /dev/null
+++ b/packages/dashboard/.storybook/preview.tsx
@@ -0,0 +1,14 @@
+import type { Preview } from "@storybook/react-vite";
+import "../src/ui/styles.css";
+
+const preview: Preview = {
+  decorators: [
+    (Story) => (
+      <div className="sq-surface" style={{ minHeight: "100vh", padding: "2rem" }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default preview;
diff --git a/packages/dashboard/package.json b/packages/dashboard/package.json
index 57ff6ed..352b00c 100644
--- a/packages/dashboard/package.json
+++ b/packages/dashboard/package.json
@@ -36,7 +36,8 @@
     "./ui": {
       "types": "./dist/ui/index.d.ts",
       "import": "./dist/ui/index.js"
-    }
+    },
+    "./ui/styles.css": "./dist/ui/styles.css"
   },
   "files": [
     "dist"
@@ -62,7 +63,6 @@
   "devDependencies": {
     "@highlightjs/cdn-assets": "^11.11.1",
     "@storybook/react-vite": "^10.4.6",
-    "@tailwindcss/vite": "^4.3.2",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
diff --git a/packages/dashboard/src/ui/Badge.stories.tsx b/packages/dashboard/src/ui/Badge.stories.tsx
new file mode 100644
index 0000000..eb8607f
--- /dev/null
+++ b/packages/dashboard/src/ui/Badge.stories.tsx
@@ -0,0 +1,41 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Badge, type JobState, type QueueState } from "./Badge";
+
+const meta = {
+  title: "Data display/Badge",
+  component: Badge,
+} satisfies Meta<typeof Badge>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Completed: Story = { args: { state: "completed" } };
+
+export const Running: Story = { args: { state: "running", dot: true } };
+
+export const Failed: Story = { args: { state: "failed" } };
+
+const ALL: (JobState | QueueState | "neutral")[] = [
+  "completed",
+  "failed",
+  "running",
+  "claimed",
+  "waiting",
+  "scheduled",
+  "canceled",
+  "active",
+  "paused",
+  "disabled",
+  "neutral",
+];
+
+export const AllStates: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexWrap: "wrap", gap: "0.5rem" }}>
+      {ALL.map((s) => (
+        <Badge key={s} state={s} dot />
+      ))}
+    </div>
+  ),
+};
diff --git a/packages/dashboard/src/ui/Badge.test.tsx b/packages/dashboard/src/ui/Badge.test.tsx
new file mode 100644
index 0000000..f0e94a6
--- /dev/null
+++ b/packages/dashboard/src/ui/Badge.test.tsx
@@ -0,0 +1,39 @@
+import { render } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Badge, type JobState } from "./Badge";
+
+describe("Badge", () => {
+  it("renders a preset state with its default label and colors", () => {
+    const { container } = render(<Badge state="completed" />);
+
+    const el = container.querySelector(".sq-badge");
+    expect(el).toHaveTextContent("Completed");
+    expect(el).toHaveStyle({ color: "#7bd6a0" });
+    // no dot by default
+    expect(el?.querySelector("span")).toBeNull();
+  });
+
+  it("uses defaults (neutral) and honors dot, children, bg/fg, className, style overrides", () => {
+    const { container } = render(
+      <Badge dot className="extra" style={{ marginTop: "2px" }} bg="rgb(17, 17, 17)" fg="rgb(238, 238, 238)">
+        Hi
+      </Badge>,
+    );
+
+    const el = container.querySelector(".sq-badge");
+    expect(el).toHaveClass("extra");
+    expect(el).toHaveTextContent("Hi");
+    expect(el).toHaveStyle({ background: "rgb(17, 17, 17)", color: "rgb(238, 238, 238)" });
+    // dot rendered
+    expect(el?.querySelector("span")).not.toBeNull();
+  });
+
+  it("falls back to the neutral preset for an unknown state", () => {
+    const { container } = render(<Badge state={"bogus" as JobState} />);
+
+    const el = container.querySelector(".sq-badge");
+    // neutral label is empty
+    expect(el).toHaveTextContent("");
+    expect(el).toHaveStyle({ color: "var(--text-secondary)" });
+  });
+});
diff --git a/packages/dashboard/src/ui/Badge.tsx b/packages/dashboard/src/ui/Badge.tsx
new file mode 100644
index 0000000..62f5618
--- /dev/null
+++ b/packages/dashboard/src/ui/Badge.tsx
@@ -0,0 +1,73 @@
+import type { CSSProperties, ReactNode } from "react";
+
+/** Job lifecycle states with a badge preset. */
+export type JobState = "completed" | "failed" | "running" | "claimed" | "waiting" | "scheduled" | "canceled";
+/** Queue states with a badge preset. */
+export type QueueState = "active" | "paused" | "disabled";
+
+/** Props for the {@link Badge} status pill. */
+export interface BadgeProps {
+  /** Job or queue state preset (drives color + default label). @default "neutral" */
+  state?: JobState | QueueState | "neutral";
+  /** Show a leading status dot. */
+  dot?: boolean;
+  /** Override background. */
+  bg?: string;
+  /** Override foreground. */
+  fg?: string;
+  children?: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}
+
+interface StatePreset {
+  bg: string;
+  fg: string;
+  label: string;
+}
+
+const STATE: Record<string, StatePreset> = {
+  completed: { bg: "rgba(79,175,117,0.18)", fg: "#7bd6a0", label: "Completed" },
+  failed: { bg: "rgba(183,82,82,0.20)", fg: "#e88d8d", label: "Failed" },
+  running: { bg: "rgba(43,124,211,0.20)", fg: "#71b0f2", label: "Running" },
+  claimed: { bg: "rgba(61,125,216,0.18)", fg: "#6fa8ec", label: "Claimed" },
+  waiting: { bg: "rgba(210,169,76,0.18)", fg: "#e0c078", label: "Waiting" },
+  scheduled: { bg: "rgba(210,169,76,0.18)", fg: "#e0c078", label: "Scheduled" },
+  canceled: { bg: "rgba(154,166,186,0.16)", fg: "#b3bdcc", label: "Canceled" },
+  active: { bg: "rgba(79,175,117,0.18)", fg: "#7bd6a0", label: "Active" },
+  paused: { bg: "rgba(210,169,76,0.18)", fg: "#e0c078", label: "Paused" },
+  disabled: { bg: "rgba(183,82,82,0.20)", fg: "#e88d8d", label: "Disabled" },
+  neutral: { bg: "var(--surface-hover)", fg: "var(--text-secondary)", label: "" },
+};
+
+/**
+ * Badge — soft-filled status pill. Presets cover every Sidequest job state
+ * (completed/failed/running/claimed/waiting/scheduled/canceled) and queue state
+ * (active/paused/disabled). Pass `state` for a preset or `bg`/`fg` to override.
+ */
+export function Badge({ state = "neutral", children, dot = false, className = "", style = {}, bg, fg }: BadgeProps) {
+  const preset = STATE[state] || STATE.neutral;
+  return (
+    <span
+      className={`sq-badge ${className}`}
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: "0.35rem",
+        height: "1.5rem",
+        padding: "0 0.6rem",
+        fontSize: "var(--text-xs)",
+        fontWeight: "var(--weight-semibold)",
+        lineHeight: 1,
+        borderRadius: "var(--radius-full)",
+        background: bg ?? preset.bg,
+        color: fg ?? preset.fg,
+        whiteSpace: "nowrap",
+        ...style,
+      }}
+    >
+      {dot && <span style={{ width: 6, height: 6, borderRadius: "var(--radius-full)", background: "currentColor" }} />}
+      {children ?? preset.label}
+    </span>
+  );
+}
diff --git a/packages/dashboard/src/ui/Card.stories.tsx b/packages/dashboard/src/ui/Card.stories.tsx
index 841cee0..5d911ba 100644
--- a/packages/dashboard/src/ui/Card.stories.tsx
+++ b/packages/dashboard/src/ui/Card.stories.tsx
@@ -2,7 +2,7 @@ import type { Meta, StoryObj } from "@storybook/react-vite";
 import { Card } from "./Card";
 
 const meta = {
-  title: "UI/Card",
+  title: "Layout/Card",
   component: Card,
   parameters: { layout: "padded" },
 } satisfies Meta<typeof Card>;
@@ -11,10 +11,22 @@ export default meta;
 
 type Story = StoryObj<typeof meta>;
 
-export const Solid: Story = {
-  args: { children: "Solid card" },
+export const Bare: Story = {
+  args: { children: "A bare panel with just body content." },
 };
 
-export const Muted: Story = {
-  args: { variant: "muted", children: "Muted card" },
+export const Titled: Story = {
+  args: { title: "Recent jobs", children: "Panel body." },
+};
+
+export const WithActions: Story = {
+  args: {
+    title: "Queues",
+    actions: (
+      <button className="sq-btn sq-btn--default" style={{ height: "2rem", padding: "0 0.7rem" }}>
+        Refresh
+      </button>
+    ),
+    children: "Panel with header actions.",
+  },
 };
diff --git a/packages/dashboard/src/ui/Card.test.tsx b/packages/dashboard/src/ui/Card.test.tsx
index 2e31015..a1e1f10 100644
--- a/packages/dashboard/src/ui/Card.test.tsx
+++ b/packages/dashboard/src/ui/Card.test.tsx
@@ -3,32 +3,48 @@ import { describe, expect, it } from "vitest";
 import { Card } from "./Card";
 
 describe("Card", () => {
-  it("renders children inside a solid surface by default", () => {
-    render(<Card>hello</Card>);
+  it("renders a bare panel (no header) with default padding", () => {
+    const { container } = render(<Card>body</Card>);
 
-    const el = screen.getByText("hello");
-    expect(el).toHaveClass("bg-surface");
-    expect(el).toHaveClass("rounded-card");
-    expect(el).toHaveClass("border-border");
+    const root = container.querySelector(".sq-card");
+    expect(root).not.toBeNull();
+    expect(screen.getByText("body")).toBeInTheDocument();
+    // no header when neither title nor actions are given
+    expect(screen.queryByRole("heading")).toBeNull();
   });
 
-  it("applies the muted variant", () => {
-    render(<Card variant="muted">muted</Card>);
+  it("renders title, actions, and honors custom padding/className/style/bodyStyle", () => {
+    const { container } = render(
+      <Card
+        title="Recent jobs"
+        actions={<button>refresh</button>}
+        padding="10px"
+        className="extra"
+        style={{ color: "rgb(1, 2, 3)" }}
+        bodyStyle={{ gap: "1px" }}
+      >
+        body
+      </Card>,
+    );
 
-    expect(screen.getByText("muted")).toHaveClass("bg-surface-muted");
+    const root = container.querySelector(".sq-card");
+    expect(root).toHaveClass("extra");
+    expect(root).toHaveStyle({ color: "rgb(1, 2, 3)" });
+    expect(screen.getByRole("heading", { name: "Recent jobs" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "refresh" })).toBeInTheDocument();
   });
 
-  it("merges a custom className and forwards native div attributes", () => {
-    render(
-      <Card className="extra" data-testid="card" role="group">
-        content
-      </Card>,
-    );
+  it("renders a header with only a title", () => {
+    render(<Card title="Only title">body</Card>);
+
+    expect(screen.getByRole("heading", { name: "Only title" })).toBeInTheDocument();
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+
+  it("renders a header with only actions", () => {
+    render(<Card actions={<button>go</button>}>body</Card>);
 
-    const el = screen.getByTestId("card");
-    expect(el).toHaveClass("extra");
-    expect(el).toHaveClass("bg-surface");
-    expect(el).toHaveAttribute("role", "group");
-    expect(el).toHaveTextContent("content");
+    expect(screen.queryByRole("heading")).toBeNull();
+    expect(screen.getByRole("button", { name: "go" })).toBeInTheDocument();
   });
 });
diff --git a/packages/dashboard/src/ui/Card.tsx b/packages/dashboard/src/ui/Card.tsx
index 9bfebef..2e3a109 100644
--- a/packages/dashboard/src/ui/Card.tsx
+++ b/packages/dashboard/src/ui/Card.tsx
@@ -1,32 +1,70 @@
-import type { HTMLAttributes } from "react";
+import type { CSSProperties, ReactNode } from "react";
 
-/** Visual variants available for {@link Card}. */
-export type CardVariant = "solid" | "muted";
-
-/** Props for the {@link Card} component. Extends the native `div` attributes. */
-export interface CardProps extends HTMLAttributes<HTMLDivElement> {
-  /** Background treatment. Defaults to `"solid"`. */
-  variant?: CardVariant;
+/** Props for the {@link Card} panel primitive. */
+export interface CardProps {
+  /** Header title. Omit for a bare panel. */
+  title?: ReactNode;
+  /** Right-aligned header actions (buttons). */
+  actions?: ReactNode;
+  /** Body padding. @default "var(--space-6)" */
+  padding?: string;
+  children?: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+  bodyStyle?: CSSProperties;
 }
 
-const variantClasses: Record<CardVariant, string> = {
-  solid: "bg-surface",
-  muted: "bg-surface-muted",
-};
-
 /**
- * Surface container used across the Sidequest dashboard. Renders a rounded,
- * bordered panel that wraps arbitrary content and forwards any native `div`
- * attributes.
+ * Card — the dashboard's panel primitive. Optional title/actions header, then a
+ * padded body. Compose stat tiles, tables, and job details inside it.
  */
-export function Card({ variant = "solid", className, children, ...rest }: CardProps) {
-  const classes = `rounded-card border border-border p-4 text-content ${variantClasses[variant]}${
-    className ? ` ${className}` : ""
-  }`;
-
+export function Card({
+  title,
+  actions,
+  children,
+  padding = "var(--space-6)",
+  className = "",
+  style = {},
+  bodyStyle = {},
+}: CardProps) {
   return (
-    <div className={classes} {...rest}>
-      {children}
+    <div
+      className={`sq-card ${className}`}
+      style={{
+        background: "var(--surface-card)",
+        border: "1px solid var(--border-default)",
+        borderRadius: "var(--radius-md)",
+        boxShadow: "var(--shadow-md)",
+        overflow: "hidden",
+        ...style,
+      }}
+    >
+      {(title != null || actions != null) && (
+        <div
+          style={{
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "space-between",
+            padding: `var(--space-4) ${padding}`,
+            borderBottom: "1px solid var(--border-subtle)",
+          }}
+        >
+          {title && (
+            <h3
+              style={{
+                margin: 0,
+                fontSize: "var(--text-lg)",
+                fontWeight: "var(--weight-semibold)",
+                color: "var(--text-strong)",
+              }}
+            >
+              {title}
+            </h3>
+          )}
+          {actions && <div style={{ display: "flex", gap: "0.5rem" }}>{actions}</div>}
+        </div>
+      )}
+      <div style={{ padding, ...bodyStyle }}>{children}</div>
     </div>
   );
 }
diff --git a/packages/dashboard/src/ui/index.ts b/packages/dashboard/src/ui/index.ts
index 6374a95..7be684c 100644
--- a/packages/dashboard/src/ui/index.ts
+++ b/packages/dashboard/src/ui/index.ts
@@ -1,2 +1,4 @@
 export { Card } from "./Card";
-export type { CardProps, CardVariant } from "./Card";
+export type { CardProps } from "./Card";
+export { Badge } from "./Badge";
+export type { BadgeProps, JobState, QueueState } from "./Badge";
diff --git a/packages/dashboard/src/ui/styles.css b/packages/dashboard/src/ui/styles.css
index 7386d58..9352244 100644
--- a/packages/dashboard/src/ui/styles.css
+++ b/packages/dashboard/src/ui/styles.css
@@ -1,17 +1,11 @@
-@import "tailwindcss";
-
-/*
- * Placeholder design tokens. These are replaced by the user's Claude design
- * system via DesignSync (run /design-login first). Tailwind v4 turns each
- * token into utilities, e.g. --color-surface -> bg-surface / border-surface.
+/* @sidequest/dashboard/ui — global stylesheet.
+ * Link this once. It is a manifest of @imports: every design token (fonts, colors,
+ * typography, spacing, radii) plus the small base layer with the `.sq-*` interaction
+ * classes. Synced from the Sidequest.js design system. Order matters.
  */
-@theme {
-  --color-surface: oklch(0.23 0.02 260);
-  --color-surface-muted: oklch(0.19 0.02 260);
-  --color-border: oklch(0.32 0.02 260);
-  --color-content: oklch(0.93 0.01 260);
-  --color-content-muted: oklch(0.72 0.02 260);
-  --color-accent: oklch(0.62 0.19 275);
-
-  --radius-card: 0.75rem;
-}
+@import "./tokens/fonts.css";
+@import "./tokens/colors.css";
+@import "./tokens/typography.css";
+@import "./tokens/spacing.css";
+@import "./tokens/radii.css";
+@import "./tokens/base.css";
diff --git a/packages/dashboard/src/ui/tokens/base.css b/packages/dashboard/src/ui/tokens/base.css
new file mode 100644
index 0000000..979e987
--- /dev/null
+++ b/packages/dashboard/src/ui/tokens/base.css
@@ -0,0 +1,64 @@
+/* Sidequest.js — Base layer
+ * Minimal resets + the ambient defaults specimen cards & kits rely on. Kept small;
+ * components style themselves via tokens. Applying `.sq-surface` to a preview root
+ * paints the app background + primary text so cards read like the real product.
+ */
+
+*, *::before, *::after { box-sizing: border-box; }
+
+.sq-surface,
+body.sq-surface {
+  margin: 0;
+  background: var(--surface-app);
+  color: var(--text-primary);
+  font-family: var(--font-sans);
+  font-size: var(--text-sm);
+  line-height: var(--leading-normal);
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+
+.sq-brand-text {
+  font-family: var(--font-brand);
+  font-weight: var(--weight-semibold);
+  letter-spacing: var(--tracking-tight);
+}
+
+.sq-mono { font-family: var(--font-mono); }
+
+/* Brand gradient text (wordmark / hero accents) */
+.sq-gradient-text {
+  background: var(--brand-gradient);
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+}
+
+/* Uppercase eyebrow / column-header treatment */
+.sq-eyebrow {
+  text-transform: uppercase;
+  letter-spacing: var(--tracking-caps);
+  font-size: var(--text-xs);
+  font-weight: var(--weight-semibold);
+  color: var(--text-muted);
+}
+
+::selection { background: var(--brand-ring); color: #fff; }
+
+/* ---- Component interaction states (inline styles can't express :hover/:focus) ---- */
+.sq-btn:not(:disabled):active { transform: translateY(0.5px); }
+.sq-btn--primary:not(:disabled):hover { background: var(--brand-primary-hover) !important; border-color: var(--brand-primary-hover) !important; }
+.sq-btn--default:not(:disabled):hover { background: var(--surface-hover) !important; }
+.sq-btn--outline:not(:disabled):hover { background: var(--surface-hover) !important; }
+.sq-btn--ghost:not(:disabled):hover { background: var(--surface-hover) !important; }
+.sq-btn--danger:not(:disabled):hover { background: rgba(183, 82, 82, 0.12) !important; border-color: var(--status-failed) !important; }
+.sq-btn:focus-visible { outline: none; box-shadow: var(--focus-ring); }
+
+.sq-input:focus, .sq-select:focus { outline: none; border-color: var(--brand-primary) !important; box-shadow: var(--focus-ring); }
+.sq-input::placeholder { color: var(--text-muted); }
+
+.sq-row { transition: background var(--duration-fast) var(--ease-standard); }
+.sq-row:hover { background: var(--surface-hover); }
+
+.sq-navitem { transition: background var(--duration-fast) var(--ease-standard), color var(--duration-fast) var(--ease-standard); }
+.sq-navitem:hover { background: var(--surface-hover); color: var(--text-strong); }
diff --git a/packages/dashboard/src/ui/tokens/colors.css b/packages/dashboard/src/ui/tokens/colors.css
new file mode 100644
index 0000000..ef10671
--- /dev/null
+++ b/packages/dashboard/src/ui/tokens/colors.css
@@ -0,0 +1,137 @@
+/* Sidequest.js — Color tokens
+ * Raw palette lifted verbatim from the dashboard's DaisyUI "sidequest-dark" theme
+ * (packages/dashboard/src/public/css/styles.css) plus the Tailwind accent tints the
+ * templates use for stat numbers. Semantic aliases sit on top and are theme-aware:
+ * :root is the canonical dark product theme; [data-theme="light"] is a derived light theme.
+ */
+
+:root {
+  /* ---- Brand blue (from logo gradient + primary #2b7cd3) ---- */
+  --sq-blue-50:  #eef5fc;
+  --sq-blue-100: #d4e6f8;
+  --sq-blue-200: #a9cdf0;
+  --sq-blue-300: #7db8ec;
+  --sq-blue-400: #4d97e0;
+  --sq-blue-500: #2b7cd3;   /* primary */
+  --sq-blue-600: #2366b4;
+  --sq-blue-700: #1d5490;
+  --sq-blue-800: #1a446f;
+  --sq-blue-900: #16304d;
+
+  /* Logo gradient endpoints (light cyan-blue -> deep blue) */
+  --sq-grad-start: #3aa0e6;
+  --sq-grad-end:   #2464c8;
+
+  /* ---- Navy / ink surfaces (base-100..300 from theme) ---- */
+  --sq-navy-950: #080c1a;
+  --sq-navy-900: #0c1226;   /* base-100  — app background */
+  --sq-navy-850: #101830;
+  --sq-navy-800: #182038;   /* base-200  — raised panels */
+  --sq-navy-700: #202a47;
+  --sq-navy-600: #2a3b5f;   /* base-300  — hover / lines */
+  --sq-slate-700: #2c3448;  /* neutral   — sidebar / cards */
+  --sq-slate-600: #38425c;
+
+  /* ---- Neutral / grey ramp (light theme + text) ---- */
+  --sq-gray-50:  #f7f9fc;
+  --sq-gray-100: #eef1f6;
+  --sq-gray-200: #e0e5ee;
+  --sq-gray-300: #cdd5e0;   /* base-content on dark */
+  --sq-gray-400: #9aa6ba;
+  --sq-gray-500: #6b7688;
+  --sq-gray-600: #4b5468;
+  --sq-gray-700: #374151;   /* secondary-content */
+  --sq-gray-800: #232b3d;
+  --sq-gray-900: #141a28;
+
+  /* ---- Status (from theme semantic colors) ---- */
+  --sq-success: #4faf75;
+  --sq-success-strong: #4ade80;   /* text-green-400 accent */
+  --sq-warning: #d2a94c;
+  --sq-warning-strong: #facc15;   /* text-yellow-400 accent */
+  --sq-error:   #b75252;
+  --sq-error-strong: #f87171;     /* text-red-400 accent */
+  --sq-info:    #3d7dd8;
+  --sq-info-strong: #60a5fa;      /* text-blue-400 accent */
+  --sq-accent:  #4c5faf;          /* accent */
+
+  /* ---- Code-block surface (near-black used in job view) ---- */
+  --sq-code-bg: #0b0f1a;
+}
+
+/* ============================================================
+   SEMANTIC ALIASES — DARK (default, canonical product theme)
+   `:root` keeps dark the no-attribute default; [data-theme="dark"]
+   is the explicit selector so consumers can force it symmetrically.
+   ============================================================ */
+:root,
+[data-theme="dark"] {
+  --surface-app:      var(--sq-navy-900);
+  --surface-raised:   var(--sq-navy-800);
+  --surface-card:     var(--sq-slate-700);
+  --surface-hover:    var(--sq-navy-600);
+  --surface-code:     var(--sq-code-bg);
+  --surface-inset:    var(--sq-navy-850);
+
+  --text-primary:     var(--sq-gray-300);
+  --text-strong:      #ffffff;
+  --text-secondary:   #9aa6ba;
+  --text-muted:       #6b7688;
+  --text-inverse:     #0c1226;
+  --text-link:        var(--sq-blue-300);
+
+  --border-subtle:    rgba(255, 255, 255, 0.06);
+  --border-default:   #2a3b5f;
+  --border-strong:    #38425c;
+
+  --brand-primary:        var(--sq-blue-500);
+  --brand-primary-hover:  var(--sq-blue-400);
+  --brand-primary-active: var(--sq-blue-600);
+  --on-brand:             #ffffff;
+  --brand-gradient:       linear-gradient(150deg, var(--sq-grad-start) 0%, var(--sq-grad-end) 100%);
+  --brand-ring:           rgba(43, 124, 211, 0.45);
+
+  /* status text accents on dark */
+  --status-running:   var(--sq-info-strong);
+  --status-completed: var(--sq-success-strong);
+  --status-failed:    var(--sq-error-strong);
+  --status-scheduled: var(--sq-warning-strong);
+
+  color-scheme: dark;
+}
+
+/* ============================================================
+   SEMANTIC ALIASES — LIGHT (derived; opt-in via data-theme)
+   ============================================================ */
+[data-theme="light"] {
+  --surface-app:      var(--sq-gray-50);
+  --surface-raised:   #ffffff;
+  --surface-card:     #ffffff;
+  --surface-hover:    var(--sq-gray-100);
+  --surface-code:     #0b0f1a;
+  --surface-inset:    var(--sq-gray-100);
+
+  --text-primary:     #1f2739;
+  --text-strong:      #0c1226;
+  --text-secondary:   #414b60;   /* 7:1 on white — was #4b5468 */
+  --text-muted:       #616b7e;   /* 4.6:1 on white — was #6b7688 (3.9:1) */
+  --text-inverse:     #ffffff;
+  --text-link:        var(--sq-blue-700);   /* 5.3:1 — was blue-600 (4.1:1) */
+
+  --border-subtle:    rgba(12, 18, 38, 0.08);
+  --border-default:   var(--sq-gray-200);
+  --border-strong:    var(--sq-gray-300);
+
+  --brand-primary:        var(--sq-blue-500);
+  --brand-primary-hover:  var(--sq-blue-600);
+  --brand-primary-active: var(--sq-blue-700);
+  --on-brand:             #ffffff;
+  --brand-ring:           rgba(43, 124, 211, 0.30);
+
+  --status-running:   var(--sq-info);
+  --status-completed: var(--sq-success);
+  --status-failed:    var(--sq-error);
+  --status-scheduled: #b7902f;
+
+  color-scheme: light;
+}
diff --git a/packages/dashboard/src/ui/tokens/fonts.css b/packages/dashboard/src/ui/tokens/fonts.css
new file mode 100644
index 0000000..ccd08ad
--- /dev/null
+++ b/packages/dashboard/src/ui/tokens/fonts.css
@@ -0,0 +1,9 @@
+/* Sidequest.js — Webfonts
+ * The shipped product renders in the platform system-ui stack (Tailwind/DaisyUI default)
+ * with `monospace` for code. This design system pairs that with two curated webfonts:
+ *  - Poppins       → brand wordmark + display, closest match to the rounded geometric
+ *                    lettering in the Sidequest.js logo (SUBSTITUTION — see README).
+ *  - JetBrains Mono → code / data / job arguments (SUBSTITUTION for generic monospace).
+ * Both load from Google Fonts. Swap the @import for local @font-face if you self-host.
+ */
+@import url('https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap');
diff --git a/packages/dashboard/src/ui/tokens/radii.css b/packages/dashboard/src/ui/tokens/radii.css
new file mode 100644
index 0000000..c0d2b6a
--- /dev/null
+++ b/packages/dashboard/src/ui/tokens/radii.css
@@ -0,0 +1,32 @@
+/* Sidequest.js — Radii & shadow tokens
+ * Radii lifted from DaisyUI theme: --radius-field .25rem, --radius-box/selector .5rem.
+ * Shadows are restrained — the product is flat/dark with hairline borders; elevation
+ * comes from surface lightness first, shadow second.
+ */
+
+:root {
+  /* ---- Corner radii ---- */
+  --radius-xs: 0.125rem;  /* 2  */
+  --radius-sm: 0.25rem;   /* 4  — inputs, selects, badges (radius-field) */
+  --radius-md: 0.5rem;    /* 8  — cards, buttons, panels (radius-box) */
+  --radius-lg: 0.75rem;   /* 12 — large panels */
+  --radius-xl: 1rem;      /* 16 */
+  --radius-full: 9999px;  /* pills, node dots, avatars */
+
+  /* ---- Elevation (tuned for dark navy surfaces) ---- */
+  --shadow-xs: 0 1px 2px rgba(0, 0, 0, 0.25);
+  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.30), 0 1px 2px rgba(0, 0, 0, 0.20);
+  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.35);
+  --shadow-lg: 0 10px 28px rgba(0, 0, 0, 0.45);
+  --shadow-glow: 0 0 0 1px var(--brand-ring), 0 6px 20px rgba(43, 124, 211, 0.25);
+
+  /* ---- Focus ring ---- */
+  --focus-ring: 0 0 0 3px var(--brand-ring);
+
+  /* ---- Motion ---- */
+  --ease-standard: cubic-bezier(0.4, 0, 0.2, 1);
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+  --duration-fast: 120ms;
+  --duration-base: 180ms;
+  --duration-slow: 280ms;
+}
diff --git a/packages/dashboard/src/ui/tokens/spacing.css b/packages/dashboard/src/ui/tokens/spacing.css
new file mode 100644
index 0000000..6663e68
--- /dev/null
+++ b/packages/dashboard/src/ui/tokens/spacing.css
@@ -0,0 +1,24 @@
+/* Sidequest.js — Spacing & sizing tokens
+ * 4px base grid. Dashboard uses Tailwind's scale (p-4, gap-4, p-6) — mirrored here.
+ */
+
+:root {
+  --space-0: 0;
+  --space-1: 0.25rem;   /* 4  */
+  --space-2: 0.5rem;    /* 8  */
+  --space-3: 0.75rem;   /* 12 */
+  --space-4: 1rem;      /* 16 — default control / card padding step */
+  --space-5: 1.25rem;   /* 20 */
+  --space-6: 1.5rem;    /* 24 — main content padding, card body */
+  --space-8: 2rem;      /* 32 — section gap */
+  --space-10: 2.5rem;   /* 40 */
+  --space-12: 3rem;     /* 48 */
+  --space-16: 4rem;     /* 64 */
+  --space-20: 5rem;     /* 80 */
+
+  /* ---- Layout constants (from dashboard) ---- */
+  --sidebar-width: 16rem;   /* w-64 */
+  --content-max: 80rem;
+  --control-height: 2.5rem; /* 40px — inputs / selects / md button */
+  --control-height-sm: 2rem;/* 32px — btn-sm */
+}
diff --git a/packages/dashboard/src/ui/tokens/typography.css b/packages/dashboard/src/ui/tokens/typography.css
new file mode 100644
index 0000000..2e3062d
--- /dev/null
+++ b/packages/dashboard/src/ui/tokens/typography.css
@@ -0,0 +1,43 @@
+/* Sidequest.js — Typography tokens
+ * Product UI renders in the platform system-ui stack (faithful to the dashboard).
+ * Poppins is reserved for the brand wordmark + display; JetBrains Mono for code/data.
+ */
+
+:root {
+  /* ---- Families ---- */
+  --font-sans: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, "Noto Sans", sans-serif;
+  --font-brand: "Poppins", var(--font-sans);
+  --font-mono: "JetBrains Mono", ui-monospace, SFMono-Regular, "SF Mono",
+    Menlo, Consolas, "Liberation Mono", monospace;
+
+  /* ---- Type scale (px in rem) ---- */
+  --text-2xs: 0.6875rem;  /* 11px — micro labels, stack traces */
+  --text-xs:  0.75rem;    /* 12px — badges, table meta */
+  --text-sm:  0.875rem;   /* 14px — body, table cells, controls */
+  --text-base:1rem;       /* 16px — default */
+  --text-lg:  1.125rem;   /* 18px — card titles */
+  --text-xl:  1.25rem;    /* 20px — sidebar brand */
+  --text-2xl: 1.5rem;     /* 24px — page headings */
+  --text-3xl: 1.875rem;   /* 30px — stat numbers / marketing */
+  --text-4xl: 2.5rem;     /* 40px — hero */
+  --text-5xl: 3.5rem;     /* 56px — hero display */
+
+  /* ---- Weights ---- */
+  --weight-regular: 400;
+  --weight-medium: 500;
+  --weight-semibold: 600;
+  --weight-bold: 700;
+
+  /* ---- Line heights ---- */
+  --leading-tight: 1.15;
+  --leading-snug: 1.35;
+  --leading-normal: 1.55;
+  --leading-relaxed: 1.7;
+
+  /* ---- Letter spacing ---- */
+  --tracking-tight: -0.02em;
+  --tracking-normal: 0;
+  --tracking-wide: 0.02em;
+  --tracking-caps: 0.06em;   /* uppercase eyebrows / table headers */
+}
diff --git a/packages/dashboard/vite.lib.config.ts b/packages/dashboard/vite.lib.config.ts
index e0867b5..531b761 100644
--- a/packages/dashboard/vite.lib.config.ts
+++ b/packages/dashboard/vite.lib.config.ts
@@ -1,10 +1,23 @@
 import react from "@vitejs/plugin-react";
+import { cpSync } from "node:fs";
 import { resolve } from "node:path";
 import { defineConfig } from "vite";
 import dts from "vite-plugin-dts";
 
 const pkgDir = import.meta.dirname;
 
+// The design tokens ship as plain CSS (consumers link `@sidequest/dashboard/ui/styles.css`).
+// The lib entry stays JS-only, so copy the token stylesheet tree into dist after the build.
+function copyTokenCss() {
+  return {
+    name: "sq-copy-ui-css",
+    closeBundle() {
+      cpSync(resolve(pkgDir, "src/ui/styles.css"), resolve(pkgDir, "dist/ui/styles.css"));
+      cpSync(resolve(pkgDir, "src/ui/tokens"), resolve(pkgDir, "dist/ui/tokens"), { recursive: true });
+    },
+  };
+}
+
 // Vite builds the `@sidequest/dashboard/ui` component library. The Express
 // server keeps its own Rollup build (see rollup.config.js) untouched.
 export default defineConfig({
@@ -17,6 +30,7 @@ export default defineConfig({
       exclude: ["src/ui/**/*.test.tsx", "src/ui/**/*.stories.tsx"],
       outDir: resolve(pkgDir, "dist/ui"),
     }),
+    copyTokenCss(),
   ],
   build: {
     outDir: resolve(pkgDir, "dist/ui"),
diff --git a/yarn.lock b/yarn.lock
index c3fd5de..56098a9 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -902,16 +902,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@emnapi/core@npm:^1.11.1":
-  version: 1.11.2
-  resolution: "@emnapi/core@npm:1.11.2"
-  dependencies:
-    "@emnapi/wasi-threads": "npm:1.2.2"
-    tslib: "npm:^2.4.0"
-  checksum: 10c0/424ca1607f498e524eb58db1095e6cc2082986edfd84a74b116d4e2c6e43b5e9d557ea7f0d7b9adf7f6d5023e25ac2ed6bd08caf0043d3d8602598d79579c2cd
-  languageName: node
-  linkType: hard
-
 "@emnapi/core@npm:^1.7.1":
   version: 1.8.1
   resolution: "@emnapi/core@npm:1.8.1"
@@ -940,15 +930,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@emnapi/runtime@npm:^1.11.1":
-  version: 1.11.2
-  resolution: "@emnapi/runtime@npm:1.11.2"
-  dependencies:
-    tslib: "npm:^2.4.0"
-  checksum: 10c0/d8d500059fe9c0864571c79ce29439c1b6fb44d7ec4ac865a2aaaa7469194e5d91ebdc820cabd37c3d373478b725a8b60771733e4743cfef41fc86d9a1f2eab0
-  languageName: node
-  linkType: hard
-
 "@emnapi/runtime@npm:^1.7.1":
   version: 1.8.1
   resolution: "@emnapi/runtime@npm:1.8.1"
@@ -976,7 +957,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@emnapi/wasi-threads@npm:1.2.2, @emnapi/wasi-threads@npm:^1.2.2":
+"@emnapi/wasi-threads@npm:1.2.2":
   version: 1.2.2
   resolution: "@emnapi/wasi-threads@npm:1.2.2"
   dependencies:
@@ -4010,7 +3991,6 @@ __metadata:
     "@sidequest/core": "workspace:*"
     "@sidequest/engine": "workspace:*"
     "@storybook/react-vite": "npm:^10.4.6"
-    "@tailwindcss/vite": "npm:^4.3.2"
     "@testing-library/dom": "npm:^10.4.1"
     "@testing-library/jest-dom": "npm:^6.9.1"
     "@testing-library/react": "npm:^16.3.2"
@@ -4359,21 +4339,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tailwindcss/node@npm:4.3.2":
-  version: 4.3.2
-  resolution: "@tailwindcss/node@npm:4.3.2"
-  dependencies:
-    "@jridgewell/remapping": "npm:^2.3.5"
-    enhanced-resolve: "npm:5.21.6"
-    jiti: "npm:^2.7.0"
-    lightningcss: "npm:1.32.0"
-    magic-string: "npm:^0.30.21"
-    source-map-js: "npm:^1.2.1"
-    tailwindcss: "npm:4.3.2"
-  checksum: 10c0/3b83caeb3a913b1a537640bbe4df3ac68dcfba1c95b5c2dedc3788bf6437b6ebb06512ec31ae1fb3aaf570eee0a2672e35ef872969a441e07861c2d248a9da3e
-  languageName: node
-  linkType: hard
-
 "@tailwindcss/oxide-android-arm64@npm:4.1.18":
   version: 4.1.18
   resolution: "@tailwindcss/oxide-android-arm64@npm:4.1.18"
@@ -4381,13 +4346,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tailwindcss/oxide-android-arm64@npm:4.3.2":
-  version: 4.3.2
-  resolution: "@tailwindcss/oxide-android-arm64@npm:4.3.2"
-  conditions: os=android & cpu=arm64
-  languageName: node
-  linkType: hard
-
 "@tailwindcss/oxide-darwin-arm64@npm:4.1.18":
   version: 4.1.18
   resolution: "@tailwindcss/oxide-darwin-arm64@npm:4.1.18"
@@ -4395,13 +4353,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tailwindcss/oxide-darwin-arm64@npm:4.3.2":
-  version: 4.3.2
-  resolution: "@tailwindcss/oxide-darwin-arm64@npm:4.3.2"
-  conditions: os=darwin & cpu=arm64
-  languageName: node
-  linkType: hard
-
 "@tailwindcss/oxide-darwin-x64@npm:4.1.18":
   version: 4.1.18
   resolution: "@tailwindcss/oxide-darwin-x64@npm:4.1.18"
@@ -4409,13 +4360,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tailwindcss/oxide-darwin-x64@npm:4.3.2":
-  version: 4.3.2
-  resolution: "@tailwindcss/oxide-darwin-x64@npm:4.3.2"
-  conditions: os=darwin & cpu=x64
-  languageName: node
-  linkType: hard
-
 "@tailwindcss/oxide-freebsd-x64@npm:4.1.18":
   version: 4.1.18
   resolution: "@tailwindcss/oxide-freebsd-x64@npm:4.1.18"
@@ -4423,13 +4367,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tailwindcss/oxide-freebsd-x64@npm:4.3.2":
-  version: 4.3.2
-  resolution: "@tailwindcss/oxide-freebsd-x64@npm:4.3.2"
-  conditions: os=freebsd & cpu=x64
-  languageName: node
-  linkType: hard
-
 "@tailwindcss/oxide-linux-arm-gnueabihf@npm:4.1.18":
   version: 4.1.18
   resolution: "@tailwindcss/oxide-linux-arm-gnueabihf@npm:4.1.18"
@@ -4437,13 +4374,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tailwindcss/oxide-linux-arm-gnueabihf@npm:4.3.2":
-  version: 4.3.2
-  resolution: "@tailwindcss/oxide-linux-arm-gnueabihf@npm:4.3.2"
-  conditions: os=linux & cpu=arm
-  languageName: node
-  linkType: hard
-
 "@tailwindcss/oxide-linux-arm64-gnu@npm:4.1.18":
   version: 4.1.18
   resolution: "@tailwindcss/oxide-linux-arm64-gnu@npm:4.1.18"
@@ -4451,13 +4381,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tailwindcss/oxide-linux-arm64-gnu@npm:4.3.2":
-  version: 4.3.2
-  resolution: "@tailwindcss/oxide-linux-arm64-gnu@npm:4.3.2"
-  conditions: os=linux & cpu=arm64 & libc=glibc
-  languageName: node
-  linkType: hard
-
 "@tailwindcss/oxide-linux-arm64-musl@npm:4.1.18":
   version: 4.1.18
   resolution: "@tailwindcss/oxide-linux-arm64-musl@npm:4.1.18"
@@ -4465,13 +4388,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tailwindcss/oxide-linux-arm64-musl@npm:4.3.2":
-  version: 4.3.2
-  resolution: "@tailwindcss/oxide-linux-arm64-musl@npm:4.3.2"
-  conditions: os=linux & cpu=arm64 & libc=musl
-  languageName: node
-  linkType: hard
-
 "@tailwindcss/oxide-linux-x64-gnu@npm:4.1.18":
   version: 4.1.18
   resolution: "@tailwindcss/oxide-linux-x64-gnu@npm:4.1.18"
@@ -4479,13 +4395,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tailwindcss/oxide-linux-x64-gnu@npm:4.3.2":
-  version: 4.3.2
-  resolution: "@tailwindcss/oxide-linux-x64-gnu@npm:4.3.2"
-  conditions: os=linux & cpu=x64 & libc=glibc
-  languageName: node
-  linkType: hard
-
 "@tailwindcss/oxide-linux-x64-musl@npm:4.1.18":
   version: 4.1.18
   resolution: "@tailwindcss/oxide-linux-x64-musl@npm:4.1.18"
@@ -4493,13 +4402,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tailwindcss/oxide-linux-x64-musl@npm:4.3.2":
-  version: 4.3.2
-  resolution: "@tailwindcss/oxide-linux-x64-musl@npm:4.3.2"
-  conditions: os=linux & cpu=x64 & libc=musl
-  languageName: node
-  linkType: hard
-
 "@tailwindcss/oxide-wasm32-wasi@npm:4.1.18":
   version: 4.1.18
   resolution: "@tailwindcss/oxide-wasm32-wasi@npm:4.1.18"
@@ -4514,20 +4416,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tailwindcss/oxide-wasm32-wasi@npm:4.3.2":
-  version: 4.3.2
-  resolution: "@tailwindcss/oxide-wasm32-wasi@npm:4.3.2"
-  dependencies:
-    "@emnapi/core": "npm:^1.11.1"
-    "@emnapi/runtime": "npm:^1.11.1"
-    "@emnapi/wasi-threads": "npm:^1.2.2"
-    "@napi-rs/wasm-runtime": "npm:^1.1.4"
-    "@tybys/wasm-util": "npm:^0.10.2"
-    tslib: "npm:^2.8.1"
-  conditions: cpu=wasm32
-  languageName: node
-  linkType: hard
-
 "@tailwindcss/oxide-win32-arm64-msvc@npm:4.1.18":
   version: 4.1.18
   resolution: "@tailwindcss/oxide-win32-arm64-msvc@npm:4.1.18"
@@ -4535,13 +4423,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tailwindcss/oxide-win32-arm64-msvc@npm:4.3.2":
-  version: 4.3.2
-  resolution: "@tailwindcss/oxide-win32-arm64-msvc@npm:4.3.2"
-  conditions: os=win32 & cpu=arm64
-  languageName: node
-  linkType: hard
-
 "@tailwindcss/oxide-win32-x64-msvc@npm:4.1.18":
   version: 4.1.18
   resolution: "@tailwindcss/oxide-win32-x64-msvc@npm:4.1.18"
@@ -4549,13 +4430,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tailwindcss/oxide-win32-x64-msvc@npm:4.3.2":
-  version: 4.3.2
-  resolution: "@tailwindcss/oxide-win32-x64-msvc@npm:4.3.2"
-  conditions: os=win32 & cpu=x64
-  languageName: node
-  linkType: hard
-
 "@tailwindcss/oxide@npm:4.1.18":
   version: 4.1.18
   resolution: "@tailwindcss/oxide@npm:4.1.18"
@@ -4601,51 +4475,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tailwindcss/oxide@npm:4.3.2":
-  version: 4.3.2
-  resolution: "@tailwindcss/oxide@npm:4.3.2"
-  dependencies:
-    "@tailwindcss/oxide-android-arm64": "npm:4.3.2"
-    "@tailwindcss/oxide-darwin-arm64": "npm:4.3.2"
-    "@tailwindcss/oxide-darwin-x64": "npm:4.3.2"
-    "@tailwindcss/oxide-freebsd-x64": "npm:4.3.2"
-    "@tailwindcss/oxide-linux-arm-gnueabihf": "npm:4.3.2"
-    "@tailwindcss/oxide-linux-arm64-gnu": "npm:4.3.2"
-    "@tailwindcss/oxide-linux-arm64-musl": "npm:4.3.2"
-    "@tailwindcss/oxide-linux-x64-gnu": "npm:4.3.2"
-    "@tailwindcss/oxide-linux-x64-musl": "npm:4.3.2"
-    "@tailwindcss/oxide-wasm32-wasi": "npm:4.3.2"
-    "@tailwindcss/oxide-win32-arm64-msvc": "npm:4.3.2"
-    "@tailwindcss/oxide-win32-x64-msvc": "npm:4.3.2"
-  dependenciesMeta:
-    "@tailwindcss/oxide-android-arm64":
-      optional: true
-    "@tailwindcss/oxide-darwin-arm64":
-      optional: true
-    "@tailwindcss/oxide-darwin-x64":
-      optional: true
-    "@tailwindcss/oxide-freebsd-x64":
-      optional: true
-    "@tailwindcss/oxide-linux-arm-gnueabihf":
-      optional: true
-    "@tailwindcss/oxide-linux-arm64-gnu":
-      optional: true
-    "@tailwindcss/oxide-linux-arm64-musl":
-      optional: true
-    "@tailwindcss/oxide-linux-x64-gnu":
-      optional: true
-    "@tailwindcss/oxide-linux-x64-musl":
-      optional: true
-    "@tailwindcss/oxide-wasm32-wasi":
-      optional: true
-    "@tailwindcss/oxide-win32-arm64-msvc":
-      optional: true
-    "@tailwindcss/oxide-win32-x64-msvc":
-      optional: true
-  checksum: 10c0/9c82a1eb1e6cd7a29118a4f9cfae5fbf83950757cfbb5e51fb212b1e17c9195632ce245f873aee6ad3133921dbb617d050d7f12530905ab1f2683d41909b1de4
-  languageName: node
-  linkType: hard
-
 "@tailwindcss/postcss@npm:^4.1.18":
   version: 4.1.18
   resolution: "@tailwindcss/postcss@npm:4.1.18"
@@ -4659,19 +4488,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tailwindcss/vite@npm:^4.3.2":
-  version: 4.3.2
-  resolution: "@tailwindcss/vite@npm:4.3.2"
-  dependencies:
-    "@tailwindcss/node": "npm:4.3.2"
-    "@tailwindcss/oxide": "npm:4.3.2"
-    tailwindcss: "npm:4.3.2"
-  peerDependencies:
-    vite: ^5.2.0 || ^6 || ^7 || ^8
-  checksum: 10c0/90fe2b5cd05b29fb555a3fc554d26187b9e9040ed762ce96e7f39490e0fac65c990fb873fb2b458385c90f70220e4ded1a898513f03b7c87e6b11bb9292ba92f
-  languageName: node
-  linkType: hard
-
 "@testing-library/dom@npm:^10.4.1":
   version: 10.4.1
   resolution: "@testing-library/dom@npm:10.4.1"
@@ -4771,7 +4587,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tybys/wasm-util@npm:^0.10.2, @tybys/wasm-util@npm:^0.10.3":
+"@tybys/wasm-util@npm:^0.10.3":
   version: 0.10.3
   resolution: "@tybys/wasm-util@npm:0.10.3"
   dependencies:
@@ -7852,16 +7668,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"enhanced-resolve@npm:5.21.6":
-  version: 5.21.6
-  resolution: "enhanced-resolve@npm:5.21.6"
-  dependencies:
-    graceful-fs: "npm:^4.2.4"
-    tapable: "npm:^2.3.3"
-  checksum: 10c0/4991b0ee020ce534c824e8f191a2cf068b9206dc6c9aef5797d41db5c45036c868145c2f0badee6084de2cc3703c7ca76426b254c6b2eac0e0e670ab4a33e528
-  languageName: node
-  linkType: hard
-
 "enhanced-resolve@npm:^5.18.3":
   version: 5.18.3
   resolution: "enhanced-resolve@npm:5.18.3"
@@ -10621,15 +10427,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"jiti@npm:^2.7.0":
-  version: 2.7.0
-  resolution: "jiti@npm:2.7.0"
-  bin:
-    jiti: lib/jiti-cli.mjs
-  checksum: 10c0/1b1e2310a490dce1aeea3da5f5dfe18273516c20ce48be2e98eb8ea452d5f3dcc8fd0cfd6d28b4052a24c5dbab6e3089b2d7e79f0bce7915b10d750929563c42
-  languageName: node
-  linkType: hard
-
 "js-tokens@npm:^10.0.0":
   version: 10.0.0
   resolution: "js-tokens@npm:10.0.0"
@@ -11242,7 +11039,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"lightningcss@npm:1.32.0, lightningcss@npm:^1.32.0":
+"lightningcss@npm:^1.32.0":
   version: 1.32.0
   resolution: "lightningcss@npm:1.32.0"
   dependencies:
@@ -16028,13 +15825,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"tailwindcss@npm:4.3.2":
-  version: 4.3.2
-  resolution: "tailwindcss@npm:4.3.2"
-  checksum: 10c0/5a377846f77590812df234446175c4c2a45111a9626fd135e46f4552a33faee0d10c4e51aa5bbec955583265d48b380fb66c96f5da2775c961d4c26157617d19
-  languageName: node
-  linkType: hard
-
 "tapable@npm:^2.2.0":
   version: 2.2.3
   resolution: "tapable@npm:2.2.3"
@@ -16042,13 +15832,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"tapable@npm:^2.3.3":
-  version: 2.3.3
-  resolution: "tapable@npm:2.3.3"
-  checksum: 10c0/47992e861053f861154e92fb4a98ac4ab47b6463717e60792dd1e8c755da0c4964cd8bb68c308a9066d6da89000b6310457b4d5d985c30de4ccc29066068cc17
-  languageName: node
-  linkType: hard
-
 "tar-fs@npm:^2.0.0":
   version: 2.1.3
   resolution: "tar-fs@npm:2.1.3"
@@ -16387,7 +16170,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"tslib@npm:^2.0.1, tslib@npm:^2.1.0, tslib@npm:^2.4.0, tslib@npm:^2.8.1":
+"tslib@npm:^2.0.1, tslib@npm:^2.1.0, tslib@npm:^2.4.0":
   version: 2.8.1
   resolution: "tslib@npm:2.8.1"
   checksum: 10c0/9c4759110a19c53f992d9aae23aac5ced636e99887b51b9e61def52611732872ff7668757d4e4c61f19691e36f4da981cd9485e869b4a7408d689f6bf1f14e62

From e905bccfe008c36a5b620e3e3a8af127ab135c21 Mon Sep 17 00:00:00 2001
From: merencia <lucas.merencia@gmail.com>
Date: Fri, 3 Jul 2026 20:13:06 -0300
Subject: [PATCH 2/7] feat(dashboard): add Icon and Button primitives

Icon resolves lucide-react glyphs by name (the design system's iconography), keeping the string-name api; Button ports the design system's action control with primary/default/outline/ghost/danger variants, three sizes, and optional leading/trailing icons. both at 100% coverage with stories. lucide-react is an optional peer, external to the lib build.
---
 packages/dashboard/package.json              |   5 +
 packages/dashboard/src/ui/Button.stories.tsx |  39 +++++++
 packages/dashboard/src/ui/Button.test.tsx    |  41 +++++++
 packages/dashboard/src/ui/Button.tsx         | 111 +++++++++++++++++++
 packages/dashboard/src/ui/Icon.stories.tsx   |  27 +++++
 packages/dashboard/src/ui/Icon.test.tsx      |  29 +++++
 packages/dashboard/src/ui/Icon.tsx           |  34 ++++++
 packages/dashboard/src/ui/index.ts           |   4 +
 packages/dashboard/vite.lib.config.ts        |   2 +-
 yarn.lock                                    |  11 ++
 10 files changed, 302 insertions(+), 1 deletion(-)
 create mode 100644 packages/dashboard/src/ui/Button.stories.tsx
 create mode 100644 packages/dashboard/src/ui/Button.test.tsx
 create mode 100644 packages/dashboard/src/ui/Button.tsx
 create mode 100644 packages/dashboard/src/ui/Icon.stories.tsx
 create mode 100644 packages/dashboard/src/ui/Icon.test.tsx
 create mode 100644 packages/dashboard/src/ui/Icon.tsx

diff --git a/packages/dashboard/package.json b/packages/dashboard/package.json
index 352b00c..e6d102d 100644
--- a/packages/dashboard/package.json
+++ b/packages/dashboard/package.json
@@ -77,6 +77,7 @@
     "feather-icons": "^4.29.2",
     "htmx.org": "^2.0.8",
     "jsdom": "^29.1.1",
+    "lucide-react": "^1.23.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "storybook": "^10.4.6",
@@ -84,10 +85,14 @@
     "vite-plugin-dts": "^5.0.3"
   },
   "peerDependencies": {
+    "lucide-react": "*",
     "react": "*",
     "react-dom": "*"
   },
   "peerDependenciesMeta": {
+    "lucide-react": {
+      "optional": true
+    },
     "react": {
       "optional": true
     },
diff --git a/packages/dashboard/src/ui/Button.stories.tsx b/packages/dashboard/src/ui/Button.stories.tsx
new file mode 100644
index 0000000..72dc328
--- /dev/null
+++ b/packages/dashboard/src/ui/Button.stories.tsx
@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Button } from "./Button";
+
+const meta = {
+  title: "Actions/Button",
+  component: Button,
+} satisfies Meta<typeof Button>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Primary: Story = { args: { variant: "primary", children: "Enqueue job" } };
+
+export const WithIcon: Story = { args: { variant: "default", icon: "play", children: "Run" } };
+
+export const Danger: Story = { args: { variant: "danger", icon: "trash-2", children: "Delete" } };
+
+export const Variants: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: "0.5rem", flexWrap: "wrap" }}>
+      <Button variant="primary">Primary</Button>
+      <Button variant="default">Default</Button>
+      <Button variant="outline">Outline</Button>
+      <Button variant="ghost">Ghost</Button>
+      <Button variant="danger">Danger</Button>
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: "0.5rem", alignItems: "center" }}>
+      <Button size="sm">Small</Button>
+      <Button size="md">Medium</Button>
+      <Button size="lg">Large</Button>
+    </div>
+  ),
+};
diff --git a/packages/dashboard/src/ui/Button.test.tsx b/packages/dashboard/src/ui/Button.test.tsx
new file mode 100644
index 0000000..239ace5
--- /dev/null
+++ b/packages/dashboard/src/ui/Button.test.tsx
@@ -0,0 +1,41 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Button } from "./Button";
+
+describe("Button", () => {
+  it("renders a default enabled button with no icons", () => {
+    render(<Button>Go</Button>);
+
+    const btn = screen.getByRole("button", { name: "Go" });
+    expect(btn).toHaveClass("sq-btn", "sq-btn--default");
+    expect(btn).toHaveAttribute("type", "button");
+    expect(btn).not.toBeDisabled();
+    expect(btn.querySelectorAll("svg")).toHaveLength(0);
+  });
+
+  it("honors variant, size, type, icons, block, active, disabled, className and style", () => {
+    render(
+      <Button
+        variant="primary"
+        size="lg"
+        type="submit"
+        icon="play"
+        iconRight="x"
+        disabled
+        block
+        active
+        className="extra"
+        style={{ margin: 0 }}
+      >
+        Run
+      </Button>,
+    );
+
+    const btn = screen.getByRole("button", { name: "Run" });
+    expect(btn).toHaveClass("sq-btn--primary", "extra");
+    expect(btn).toHaveAttribute("type", "submit");
+    expect(btn).toBeDisabled();
+    // leading + trailing icons
+    expect(btn.querySelectorAll("svg")).toHaveLength(2);
+  });
+});
diff --git a/packages/dashboard/src/ui/Button.tsx b/packages/dashboard/src/ui/Button.tsx
new file mode 100644
index 0000000..4c9feab
--- /dev/null
+++ b/packages/dashboard/src/ui/Button.tsx
@@ -0,0 +1,111 @@
+import type { ButtonHTMLAttributes, CSSProperties } from "react";
+import { Icon } from "./Icon";
+
+/** Visual treatments for {@link Button}. */
+export type ButtonVariant = "primary" | "default" | "outline" | "ghost" | "danger";
+/** Sizes for {@link Button}. */
+export type ButtonSize = "sm" | "md" | "lg";
+
+/** Props for the {@link Button} action control. Extends the native `button` attributes. */
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Visual treatment. @default "default" */
+  variant?: ButtonVariant;
+  /** @default "md" */
+  size?: ButtonSize;
+  /** Leading Lucide icon name. */
+  icon?: string;
+  /** Trailing Lucide icon name. */
+  iconRight?: string;
+  /** Full-width. */
+  block?: boolean;
+  /** Pressed/selected look (e.g. active pagination). */
+  active?: boolean;
+}
+
+interface SizeSpec {
+  height: string;
+  padding: string;
+  font: string;
+  gap: string;
+  icon: number;
+}
+
+const SIZES: Record<ButtonSize, SizeSpec> = {
+  sm: { height: "var(--control-height-sm)", padding: "0 0.7rem", font: "var(--text-xs)", gap: "0.35rem", icon: 14 },
+  md: { height: "var(--control-height)", padding: "0 1rem", font: "var(--text-sm)", gap: "0.45rem", icon: 16 },
+  lg: { height: "2.75rem", padding: "0 1.35rem", font: "var(--text-base)", gap: "0.5rem", icon: 18 },
+};
+
+/**
+ * Button — the dashboard's primary action control. Subtle raised default, solid brand
+ * primary, hairline outline, ghost (nav), and danger treatments, with an optional
+ * leading/trailing Lucide icon.
+ */
+export function Button({
+  children,
+  variant = "default",
+  size = "md",
+  icon,
+  iconRight,
+  disabled = false,
+  block = false,
+  active = false,
+  type = "button",
+  className = "",
+  style = {},
+  ...rest
+}: ButtonProps) {
+  const s = SIZES[size];
+
+  const base: CSSProperties = {
+    display: block ? "flex" : "inline-flex",
+    width: block ? "100%" : "auto",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: s.gap,
+    height: s.height,
+    padding: s.padding,
+    fontFamily: "var(--font-sans)",
+    fontSize: s.font,
+    fontWeight: "var(--weight-medium)",
+    lineHeight: 1,
+    whiteSpace: "nowrap",
+    borderRadius: "var(--radius-sm)",
+    border: "1px solid transparent",
+    cursor: disabled ? "not-allowed" : "pointer",
+    opacity: disabled ? 0.5 : 1,
+    transition:
+      "background var(--duration-fast) var(--ease-standard), border-color var(--duration-fast) var(--ease-standard), transform var(--duration-fast) var(--ease-standard)",
+    userSelect: "none",
+  };
+
+  const variants: Record<ButtonVariant, CSSProperties> = {
+    primary: { background: "var(--brand-primary)", color: "var(--on-brand)", borderColor: "var(--brand-primary)" },
+    default: {
+      background: active ? "var(--surface-hover)" : "var(--surface-raised)",
+      color: "var(--text-primary)",
+      borderColor: "var(--border-strong)",
+    },
+    outline: { background: "transparent", color: "var(--text-primary)", borderColor: "var(--border-strong)" },
+    ghost: {
+      background: active ? "var(--surface-hover)" : "transparent",
+      color: "var(--text-primary)",
+      borderColor: "transparent",
+    },
+    danger: { background: "transparent", color: "var(--status-failed)", borderColor: "var(--border-strong)" },
+  };
+
+  return (
+    <button
+      type={type}
+      disabled={disabled}
+      className={`sq-btn sq-btn--${variant} ${className}`}
+      style={{ ...base, ...variants[variant], ...style }}
+      {...rest}
+    >
+      {icon && <Icon name={icon} size={s.icon} />}
+      {children}
+      {iconRight && <Icon name={iconRight} size={s.icon} />}
+    </button>
+  );
+}
diff --git a/packages/dashboard/src/ui/Icon.stories.tsx b/packages/dashboard/src/ui/Icon.stories.tsx
new file mode 100644
index 0000000..790360a
--- /dev/null
+++ b/packages/dashboard/src/ui/Icon.stories.tsx
@@ -0,0 +1,27 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Icon } from "./Icon";
+
+const meta = {
+  title: "Actions/Icon",
+  component: Icon,
+} satisfies Meta<typeof Icon>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Play: Story = { args: { name: "play" } };
+
+export const Large: Story = { args: { name: "refresh-ccw", size: 32 } };
+
+const NAMES = ["play", "x", "refresh-ccw", "trash-2", "clock", "activity", "check-circle", "x-circle", "pause"];
+
+export const Gallery: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: "1rem", color: "var(--text-primary)" }}>
+      {NAMES.map((n) => (
+        <Icon key={n} name={n} size={20} />
+      ))}
+    </div>
+  ),
+};
diff --git a/packages/dashboard/src/ui/Icon.test.tsx b/packages/dashboard/src/ui/Icon.test.tsx
new file mode 100644
index 0000000..6d725ee
--- /dev/null
+++ b/packages/dashboard/src/ui/Icon.test.tsx
@@ -0,0 +1,29 @@
+import { render } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Icon } from "./Icon";
+
+describe("Icon", () => {
+  it("renders a lucide glyph for a known name with defaults", () => {
+    const { container } = render(<Icon name="play" />);
+
+    const svg = container.querySelector("svg");
+    expect(svg).not.toBeNull();
+    expect(svg).toHaveAttribute("width", "16");
+    expect(svg).toHaveAttribute("aria-hidden", "true");
+  });
+
+  it("resolves multi-segment names and honors size/strokeWidth/rest props", () => {
+    const { container } = render(<Icon name="refresh-ccw" size={24} strokeWidth={3} className="x" />);
+
+    const svg = container.querySelector("svg");
+    expect(svg).toHaveAttribute("width", "24");
+    expect(svg).toHaveAttribute("stroke-width", "3");
+    expect(svg).toHaveClass("x");
+  });
+
+  it("renders nothing for an unknown name", () => {
+    const { container } = render(<Icon name="definitely-not-an-icon" />);
+
+    expect(container.querySelector("svg")).toBeNull();
+  });
+});
diff --git a/packages/dashboard/src/ui/Icon.tsx b/packages/dashboard/src/ui/Icon.tsx
new file mode 100644
index 0000000..bb77a39
--- /dev/null
+++ b/packages/dashboard/src/ui/Icon.tsx
@@ -0,0 +1,34 @@
+import { icons, type LucideProps } from "lucide-react";
+import type { ComponentType } from "react";
+
+/** Props for the {@link Icon} component. Extends the underlying Lucide SVG props. */
+export interface IconProps extends Omit<LucideProps, "ref"> {
+  /** Lucide icon name, kebab or space separated, e.g. "play", "x", "refresh-ccw". */
+  name: string;
+  /** Pixel size. @default 16 */
+  size?: number;
+  /** @default 2 */
+  strokeWidth?: number;
+}
+
+/** "refresh-ccw" | "refresh ccw" -> "RefreshCcw" (the Lucide component key). */
+function toPascalCase(name: string): string {
+  return name
+    .split(/[-_ ]+/)
+    .filter(Boolean)
+    .map((part) => part[0].toUpperCase() + part.slice(1))
+    .join("");
+}
+
+/**
+ * Icon — a Lucide glyph resolved by name (Feather's successor; the design system's
+ * iconography). Renders `currentColor`, so it inherits the surrounding text color.
+ * Returns nothing for an unknown name.
+ */
+export function Icon({ name, size = 16, strokeWidth = 2, ...rest }: IconProps) {
+  const Glyph = icons[toPascalCase(name) as keyof typeof icons] as ComponentType<LucideProps> | undefined;
+  if (!Glyph) {
+    return null;
+  }
+  return <Glyph size={size} strokeWidth={strokeWidth} aria-hidden {...rest} />;
+}
diff --git a/packages/dashboard/src/ui/index.ts b/packages/dashboard/src/ui/index.ts
index 7be684c..6e07bb4 100644
--- a/packages/dashboard/src/ui/index.ts
+++ b/packages/dashboard/src/ui/index.ts
@@ -2,3 +2,7 @@ export { Card } from "./Card";
 export type { CardProps } from "./Card";
 export { Badge } from "./Badge";
 export type { BadgeProps, JobState, QueueState } from "./Badge";
+export { Icon } from "./Icon";
+export type { IconProps } from "./Icon";
+export { Button } from "./Button";
+export type { ButtonProps, ButtonSize, ButtonVariant } from "./Button";
diff --git a/packages/dashboard/vite.lib.config.ts b/packages/dashboard/vite.lib.config.ts
index 531b761..3376f9e 100644
--- a/packages/dashboard/vite.lib.config.ts
+++ b/packages/dashboard/vite.lib.config.ts
@@ -41,7 +41,7 @@ export default defineConfig({
       fileName: () => "index.js",
     },
     rollupOptions: {
-      external: ["react", "react-dom", "react/jsx-runtime"],
+      external: ["react", "react-dom", "react/jsx-runtime", "lucide-react"],
     },
   },
 });
diff --git a/yarn.lock b/yarn.lock
index 56098a9..730144f 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -4009,6 +4009,7 @@ __metadata:
     feather-icons: "npm:^4.29.2"
     htmx.org: "npm:^2.0.8"
     jsdom: "npm:^29.1.1"
+    lucide-react: "npm:^1.23.0"
     morgan: "npm:^1.10.1"
     react: "npm:^19.2.7"
     react-dom: "npm:^19.2.7"
@@ -4016,6 +4017,7 @@ __metadata:
     vite: "npm:^8.1.3"
     vite-plugin-dts: "npm:^5.0.3"
   peerDependencies:
+    lucide-react: "*"
     react: "*"
     react-dom: "*"
   peerDependenciesMeta:
@@ -11329,6 +11331,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"lucide-react@npm:^1.23.0":
+  version: 1.23.0
+  resolution: "lucide-react@npm:1.23.0"
+  peerDependencies:
+    react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
+  checksum: 10c0/1cb2108d81c9713e20dd1beb7b6ac5bfc17307d5f38388f84921cf6a124efb4b933c73929bede42f00bd08aa2df340b0904acdf4fb90206ccd52971e943e775b
+  languageName: node
+  linkType: hard
+
 "lz-string@npm:^1.5.0":
   version: 1.5.0
   resolution: "lz-string@npm:1.5.0"

From 32f3b50b27a7828ad55c16895719bd352d6a9f06 Mon Sep 17 00:00:00 2001
From: merencia <lucas.merencia@gmail.com>
Date: Fri, 3 Jul 2026 20:45:10 -0300
Subject: [PATCH 3/7] feat(dashboard): add remaining ui primitives and theme
 switching

ports the rest of the design system into @sidequest/dashboard/ui: Input, Select, FormField, Table, Pagination, StatCard, StepProgress, CodeBlock, Sidebar, NavItem and ThemeToggle. every primitive is faithful to the design system (css-variable tokens + inline styles), typed, and at 100% test coverage with storybook stories.

the ui library is now 15 components. storybook gets a dark/light toolbar switch so every component can be verified in both themes; the tokens already flip via [data-theme], so Card/Button/Icon and friends adapt with no component changes.
---
 packages/dashboard/.storybook/preview.tsx     |  28 ++++-
 .../dashboard/src/ui/CodeBlock.stories.tsx    |  22 ++++
 packages/dashboard/src/ui/CodeBlock.test.tsx  |  22 ++++
 packages/dashboard/src/ui/CodeBlock.tsx       |  41 +++++++
 .../dashboard/src/ui/FormField.stories.tsx    |  30 +++++
 packages/dashboard/src/ui/FormField.test.tsx  |  28 +++++
 packages/dashboard/src/ui/FormField.tsx       |  39 ++++++
 packages/dashboard/src/ui/Icon.stories.tsx    |   2 +-
 packages/dashboard/src/ui/Input.stories.tsx   |  18 +++
 packages/dashboard/src/ui/Input.test.tsx      |  21 ++++
 packages/dashboard/src/ui/Input.tsx           |  38 ++++++
 packages/dashboard/src/ui/NavItem.stories.tsx |  26 ++++
 packages/dashboard/src/ui/NavItem.test.tsx    |  32 +++++
 packages/dashboard/src/ui/NavItem.tsx         |  45 +++++++
 .../dashboard/src/ui/Pagination.stories.tsx   |  18 +++
 packages/dashboard/src/ui/Pagination.test.tsx |  22 ++++
 packages/dashboard/src/ui/Pagination.tsx      |  51 ++++++++
 packages/dashboard/src/ui/Select.stories.tsx  |  35 ++++++
 packages/dashboard/src/ui/Select.test.tsx     |  35 ++++++
 packages/dashboard/src/ui/Select.tsx          |  59 +++++++++
 packages/dashboard/src/ui/Sidebar.stories.tsx |  24 ++++
 packages/dashboard/src/ui/Sidebar.test.tsx    |  29 +++++
 packages/dashboard/src/ui/Sidebar.tsx         |  90 ++++++++++++++
 .../dashboard/src/ui/StatCard.stories.tsx     |  27 +++++
 packages/dashboard/src/ui/StatCard.test.tsx   |  23 ++++
 packages/dashboard/src/ui/StatCard.tsx        |  60 ++++++++++
 .../dashboard/src/ui/StepProgress.stories.tsx |  45 +++++++
 .../dashboard/src/ui/StepProgress.test.tsx    |  26 ++++
 packages/dashboard/src/ui/StepProgress.tsx    |  95 +++++++++++++++
 packages/dashboard/src/ui/Table.stories.tsx   |  30 +++++
 packages/dashboard/src/ui/Table.test.tsx      |  41 +++++++
 packages/dashboard/src/ui/Table.tsx           | 103 ++++++++++++++++
 .../dashboard/src/ui/ThemeToggle.stories.tsx  |  15 +++
 .../dashboard/src/ui/ThemeToggle.test.tsx     |  77 ++++++++++++
 packages/dashboard/src/ui/ThemeToggle.tsx     | 113 ++++++++++++++++++
 packages/dashboard/src/ui/index.ts            |  30 ++++-
 36 files changed, 1430 insertions(+), 10 deletions(-)
 create mode 100644 packages/dashboard/src/ui/CodeBlock.stories.tsx
 create mode 100644 packages/dashboard/src/ui/CodeBlock.test.tsx
 create mode 100644 packages/dashboard/src/ui/CodeBlock.tsx
 create mode 100644 packages/dashboard/src/ui/FormField.stories.tsx
 create mode 100644 packages/dashboard/src/ui/FormField.test.tsx
 create mode 100644 packages/dashboard/src/ui/FormField.tsx
 create mode 100644 packages/dashboard/src/ui/Input.stories.tsx
 create mode 100644 packages/dashboard/src/ui/Input.test.tsx
 create mode 100644 packages/dashboard/src/ui/Input.tsx
 create mode 100644 packages/dashboard/src/ui/NavItem.stories.tsx
 create mode 100644 packages/dashboard/src/ui/NavItem.test.tsx
 create mode 100644 packages/dashboard/src/ui/NavItem.tsx
 create mode 100644 packages/dashboard/src/ui/Pagination.stories.tsx
 create mode 100644 packages/dashboard/src/ui/Pagination.test.tsx
 create mode 100644 packages/dashboard/src/ui/Pagination.tsx
 create mode 100644 packages/dashboard/src/ui/Select.stories.tsx
 create mode 100644 packages/dashboard/src/ui/Select.test.tsx
 create mode 100644 packages/dashboard/src/ui/Select.tsx
 create mode 100644 packages/dashboard/src/ui/Sidebar.stories.tsx
 create mode 100644 packages/dashboard/src/ui/Sidebar.test.tsx
 create mode 100644 packages/dashboard/src/ui/Sidebar.tsx
 create mode 100644 packages/dashboard/src/ui/StatCard.stories.tsx
 create mode 100644 packages/dashboard/src/ui/StatCard.test.tsx
 create mode 100644 packages/dashboard/src/ui/StatCard.tsx
 create mode 100644 packages/dashboard/src/ui/StepProgress.stories.tsx
 create mode 100644 packages/dashboard/src/ui/StepProgress.test.tsx
 create mode 100644 packages/dashboard/src/ui/StepProgress.tsx
 create mode 100644 packages/dashboard/src/ui/Table.stories.tsx
 create mode 100644 packages/dashboard/src/ui/Table.test.tsx
 create mode 100644 packages/dashboard/src/ui/Table.tsx
 create mode 100644 packages/dashboard/src/ui/ThemeToggle.stories.tsx
 create mode 100644 packages/dashboard/src/ui/ThemeToggle.test.tsx
 create mode 100644 packages/dashboard/src/ui/ThemeToggle.tsx

diff --git a/packages/dashboard/.storybook/preview.tsx b/packages/dashboard/.storybook/preview.tsx
index 5e18b62..12456aa 100644
--- a/packages/dashboard/.storybook/preview.tsx
+++ b/packages/dashboard/.storybook/preview.tsx
@@ -2,12 +2,30 @@ import type { Preview } from "@storybook/react-vite";
 import "../src/ui/styles.css";
 
 const preview: Preview = {
+  globalTypes: {
+    theme: {
+      description: "Design system theme",
+      defaultValue: "dark",
+      toolbar: {
+        title: "Theme",
+        icon: "circlehollow",
+        items: [
+          { value: "dark", title: "Dark" },
+          { value: "light", title: "Light" },
+        ],
+        dynamicTitle: true,
+      },
+    },
+  },
   decorators: [
-    (Story) => (
-      <div className="sq-surface" style={{ minHeight: "100vh", padding: "2rem" }}>
-        <Story />
-      </div>
-    ),
+    (Story, context) => {
+      const theme = context.globals.theme ?? "dark";
+      return (
+        <div className="sq-surface" data-theme={theme} style={{ minHeight: "100vh", padding: "2rem" }}>
+          <Story />
+        </div>
+      );
+    },
   ],
 };
 
diff --git a/packages/dashboard/src/ui/CodeBlock.stories.tsx b/packages/dashboard/src/ui/CodeBlock.stories.tsx
new file mode 100644
index 0000000..77b84b8
--- /dev/null
+++ b/packages/dashboard/src/ui/CodeBlock.stories.tsx
@@ -0,0 +1,22 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { CodeBlock } from "./CodeBlock";
+
+const meta = {
+  title: "Data display/CodeBlock",
+  component: CodeBlock,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof CodeBlock>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Args: Story = {
+  args: { code: { to: "user@example.com", template: "welcome", attempts: 1 } },
+};
+
+export const StackTrace: Story = {
+  args: {
+    code: "Error: connection refused\n    at SendEmailJob.run (jobs/send-email.ts:12:15)\n    at Runner.perform (runner.ts:88:9)",
+  },
+};
diff --git a/packages/dashboard/src/ui/CodeBlock.test.tsx b/packages/dashboard/src/ui/CodeBlock.test.tsx
new file mode 100644
index 0000000..0b425bf
--- /dev/null
+++ b/packages/dashboard/src/ui/CodeBlock.test.tsx
@@ -0,0 +1,22 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { CodeBlock } from "./CodeBlock";
+
+describe("CodeBlock", () => {
+  it("renders a string verbatim with defaults", () => {
+    const { container } = render(<CodeBlock code="hello world" />);
+
+    expect(screen.getByText("hello world")).toBeInTheDocument();
+    expect(container.querySelector(".sq-codeblock")).not.toBeNull();
+  });
+
+  it("pretty-prints an object as JSON and honors language/maxHeight/className", () => {
+    const { container } = render(
+      <CodeBlock code={{ a: 1, b: "x" }} language="json" maxHeight="10rem" className="extra" style={{ opacity: 1 }} />,
+    );
+
+    expect(container.querySelector(".sq-codeblock")).toHaveClass("extra");
+    expect(container.querySelector("code")).toHaveAttribute("data-language", "json");
+    expect(screen.getByText(/"a": 1/)).toBeInTheDocument();
+  });
+});
diff --git a/packages/dashboard/src/ui/CodeBlock.tsx b/packages/dashboard/src/ui/CodeBlock.tsx
new file mode 100644
index 0000000..1bae134
--- /dev/null
+++ b/packages/dashboard/src/ui/CodeBlock.tsx
@@ -0,0 +1,41 @@
+import type { CSSProperties } from "react";
+
+/** Props for the {@link CodeBlock} monospace panel. */
+export interface CodeBlockProps {
+  /** String, or an object that will be pretty-printed as JSON. */
+  code: string | object;
+  language?: string;
+  /** @default "15rem" */
+  maxHeight?: string;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/**
+ * CodeBlock — near-black monospace panel for job arguments, results, and stack traces.
+ * Pass a string, or an object which is pretty-printed as JSON.
+ */
+export function CodeBlock({ code, language, maxHeight = "15rem", className = "", style = {} }: CodeBlockProps) {
+  const text = typeof code === "string" ? code : JSON.stringify(code, null, 2);
+  return (
+    <pre
+      className={`sq-codeblock ${className}`}
+      style={{
+        margin: 0,
+        background: "var(--surface-code)",
+        border: "1px solid var(--border-default)",
+        borderRadius: "var(--radius-md)",
+        padding: "0.85rem 1rem",
+        fontFamily: "var(--font-mono)",
+        fontSize: "var(--text-xs)",
+        lineHeight: 1.6,
+        color: "var(--text-primary)",
+        maxHeight,
+        overflow: "auto",
+        ...style,
+      }}
+    >
+      <code data-language={language}>{text}</code>
+    </pre>
+  );
+}
diff --git a/packages/dashboard/src/ui/FormField.stories.tsx b/packages/dashboard/src/ui/FormField.stories.tsx
new file mode 100644
index 0000000..1d5eb3b
--- /dev/null
+++ b/packages/dashboard/src/ui/FormField.stories.tsx
@@ -0,0 +1,30 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { FormField } from "./FormField";
+import { Input } from "./Input";
+
+const meta = {
+  title: "Forms/FormField",
+  component: FormField,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof FormField>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const WithInput: Story = {
+  args: {
+    label: "Job class",
+    width: "16rem",
+    children: <Input placeholder="SendEmailJob" />,
+  },
+};
+
+export const WithHint: Story = {
+  args: {
+    label: "Cron",
+    hint: "in-memory, per instance",
+    width: "16rem",
+    children: <Input placeholder="0 * * * *" />,
+  },
+};
diff --git a/packages/dashboard/src/ui/FormField.test.tsx b/packages/dashboard/src/ui/FormField.test.tsx
new file mode 100644
index 0000000..bb41750
--- /dev/null
+++ b/packages/dashboard/src/ui/FormField.test.tsx
@@ -0,0 +1,28 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { FormField } from "./FormField";
+
+describe("FormField", () => {
+  it("renders only the control when no label or hint is given", () => {
+    render(
+      <FormField>
+        <input aria-label="bare" />
+      </FormField>,
+    );
+
+    expect(screen.getByLabelText("bare")).toBeInTheDocument();
+    expect(screen.queryByText("Name")).toBeNull();
+  });
+
+  it("renders label, hint, fixed width and className", () => {
+    const { container } = render(
+      <FormField label="Name" htmlFor="n" width="12rem" hint="required" className="extra">
+        <input id="n" />
+      </FormField>,
+    );
+
+    expect(screen.getByText("Name")).toBeInTheDocument();
+    expect(screen.getByText("required")).toBeInTheDocument();
+    expect(container.querySelector(".sq-field")).toHaveClass("extra");
+  });
+});
diff --git a/packages/dashboard/src/ui/FormField.tsx b/packages/dashboard/src/ui/FormField.tsx
new file mode 100644
index 0000000..55b8e81
--- /dev/null
+++ b/packages/dashboard/src/ui/FormField.tsx
@@ -0,0 +1,39 @@
+import type { CSSProperties, ReactNode } from "react";
+
+/** Props for the {@link FormField} label + control wrapper. */
+export interface FormFieldProps {
+  /** Label text above the control. */
+  label?: string;
+  htmlFor?: string;
+  /** Fixed width, e.g. "12rem" (filter bars). */
+  width?: string;
+  /** Helper text below the control. */
+  hint?: string;
+  children?: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/**
+ * FormField — label + control wrapper for filter bars and forms. Optional label above
+ * and hint below the control.
+ */
+export function FormField({ label, htmlFor, width, hint, className = "", style = {}, children }: FormFieldProps) {
+  return (
+    <div
+      className={`sq-field ${className}`}
+      style={{ display: "flex", flexDirection: "column", gap: "0.35rem", width: width ?? "auto", ...style }}
+    >
+      {label != null && (
+        <label
+          htmlFor={htmlFor}
+          style={{ fontSize: "var(--text-xs)", fontWeight: "var(--weight-medium)", color: "var(--text-secondary)" }}
+        >
+          {label}
+        </label>
+      )}
+      {children}
+      {hint != null && <span style={{ fontSize: "var(--text-2xs)", color: "var(--text-muted)" }}>{hint}</span>}
+    </div>
+  );
+}
diff --git a/packages/dashboard/src/ui/Icon.stories.tsx b/packages/dashboard/src/ui/Icon.stories.tsx
index 790360a..c3e90bf 100644
--- a/packages/dashboard/src/ui/Icon.stories.tsx
+++ b/packages/dashboard/src/ui/Icon.stories.tsx
@@ -14,7 +14,7 @@ export const Play: Story = { args: { name: "play" } };
 
 export const Large: Story = { args: { name: "refresh-ccw", size: 32 } };
 
-const NAMES = ["play", "x", "refresh-ccw", "trash-2", "clock", "activity", "check-circle", "x-circle", "pause"];
+const NAMES = ["play", "x", "refresh-ccw", "trash-2", "clock", "activity", "circle-check", "circle-x", "pause"];
 
 export const Gallery: Story = {
   render: () => (
diff --git a/packages/dashboard/src/ui/Input.stories.tsx b/packages/dashboard/src/ui/Input.stories.tsx
new file mode 100644
index 0000000..ba57f9a
--- /dev/null
+++ b/packages/dashboard/src/ui/Input.stories.tsx
@@ -0,0 +1,18 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Input } from "./Input";
+
+const meta = {
+  title: "Forms/Input",
+  component: Input,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Input>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { args: { placeholder: "Search jobs…" } };
+
+export const Small: Story = { args: { size: "sm", placeholder: "Filter" } };
+
+export const Invalid: Story = { args: { invalid: true, defaultValue: "bad value" } };
diff --git a/packages/dashboard/src/ui/Input.test.tsx b/packages/dashboard/src/ui/Input.test.tsx
new file mode 100644
index 0000000..4ca3531
--- /dev/null
+++ b/packages/dashboard/src/ui/Input.test.tsx
@@ -0,0 +1,21 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Input } from "./Input";
+
+describe("Input", () => {
+  it("renders a text input with defaults", () => {
+    render(<Input aria-label="name" />);
+
+    const input = screen.getByLabelText("name");
+    expect(input).toHaveClass("sq-input");
+    expect(input).toHaveAttribute("type", "text");
+  });
+
+  it("honors type, small size, invalid, className and style", () => {
+    render(<Input aria-label="age" type="number" size="sm" invalid className="extra" style={{ marginTop: "1px" }} />);
+
+    const input = screen.getByLabelText("age");
+    expect(input).toHaveClass("sq-input", "extra");
+    expect(input).toHaveAttribute("type", "number");
+  });
+});
diff --git a/packages/dashboard/src/ui/Input.tsx b/packages/dashboard/src/ui/Input.tsx
new file mode 100644
index 0000000..48ba8f9
--- /dev/null
+++ b/packages/dashboard/src/ui/Input.tsx
@@ -0,0 +1,38 @@
+import type { InputHTMLAttributes } from "react";
+
+/** Props for the {@link Input} field. Extends the native `input` attributes. */
+export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size"> {
+  /** @default "md" */
+  size?: "sm" | "md";
+  /** Red border for validation errors. */
+  invalid?: boolean;
+}
+
+/**
+ * Input — text/number/datetime field, matching the dashboard's filter-bar inputs.
+ * Pair with {@link FormField} for a label.
+ */
+export function Input({ type = "text", size = "md", invalid = false, className = "", style = {}, ...rest }: InputProps) {
+  const height = size === "sm" ? "var(--control-height-sm)" : "var(--control-height)";
+  return (
+    <input
+      type={type}
+      className={`sq-input ${className}`}
+      style={{
+        height,
+        width: "100%",
+        padding: "0 0.75rem",
+        fontFamily: "var(--font-sans)",
+        fontSize: "var(--text-sm)",
+        color: "var(--text-primary)",
+        background: "var(--surface-raised)",
+        border: `1px solid ${invalid ? "var(--status-failed)" : "var(--border-strong)"}`,
+        borderRadius: "var(--radius-sm)",
+        transition:
+          "border-color var(--duration-fast) var(--ease-standard), box-shadow var(--duration-fast) var(--ease-standard)",
+        ...style,
+      }}
+      {...rest}
+    />
+  );
+}
diff --git a/packages/dashboard/src/ui/NavItem.stories.tsx b/packages/dashboard/src/ui/NavItem.stories.tsx
new file mode 100644
index 0000000..778db43
--- /dev/null
+++ b/packages/dashboard/src/ui/NavItem.stories.tsx
@@ -0,0 +1,26 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { NavItem } from "./NavItem";
+
+const meta = {
+  title: "Navigation/NavItem",
+  component: NavItem,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof NavItem>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Active: Story = { args: { label: "Dashboard", icon: "layout-dashboard", active: true } };
+
+export const Inactive: Story = { args: { label: "Jobs", icon: "list" } };
+
+export const List: Story = {
+  render: () => (
+    <div style={{ width: "14rem", display: "flex", flexDirection: "column", gap: "0.25rem" }}>
+      <NavItem label="Dashboard" icon="layout-dashboard" active />
+      <NavItem label="Jobs" icon="list" />
+      <NavItem label="Queues" icon="layers" />
+    </div>
+  ),
+};
diff --git a/packages/dashboard/src/ui/NavItem.test.tsx b/packages/dashboard/src/ui/NavItem.test.tsx
new file mode 100644
index 0000000..11ac998
--- /dev/null
+++ b/packages/dashboard/src/ui/NavItem.test.tsx
@@ -0,0 +1,32 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { NavItem } from "./NavItem";
+
+describe("NavItem", () => {
+  it("renders an inactive link with no icon by default", () => {
+    const { container } = render(<NavItem label="Jobs" />);
+
+    const link = screen.getByRole("link", { name: "Jobs" });
+    expect(link).toHaveClass("sq-navitem");
+    expect(link).toHaveAttribute("href", "#");
+    expect(container.querySelector("svg")).toBeNull();
+  });
+
+  it("renders an inactive link with an icon (muted icon color)", () => {
+    const { container } = render(<NavItem label="Jobs" icon="list" />);
+
+    expect(screen.getByRole("link", { name: /Jobs/ })).toBeInTheDocument();
+    expect(container.querySelector("svg")).not.toBeNull();
+  });
+
+  it("renders an active link with an icon, href, className and style", () => {
+    const { container } = render(
+      <NavItem label="Queues" icon="layers" active href="/queues" className="extra" style={{ opacity: 1 }} />,
+    );
+
+    const link = screen.getByRole("link", { name: /Queues/ });
+    expect(link).toHaveClass("extra");
+    expect(link).toHaveAttribute("href", "/queues");
+    expect(container.querySelector("svg")).not.toBeNull();
+  });
+});
diff --git a/packages/dashboard/src/ui/NavItem.tsx b/packages/dashboard/src/ui/NavItem.tsx
new file mode 100644
index 0000000..2bba8dd
--- /dev/null
+++ b/packages/dashboard/src/ui/NavItem.tsx
@@ -0,0 +1,45 @@
+import type { CSSProperties, MouseEvent } from "react";
+import { Icon } from "./Icon";
+
+/** Props for the {@link NavItem} sidebar link. */
+export interface NavItemProps {
+  label: string;
+  /** Lucide icon name. */
+  icon?: string;
+  active?: boolean;
+  href?: string;
+  onClick?: (e: MouseEvent) => void;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/**
+ * NavItem — a single sidebar link. The active state gets a subtle raised fill and a
+ * brand left-accent; hover lightens (see `.sq-navitem` in the base layer).
+ */
+export function NavItem({ label, icon, active = false, href = "#", onClick, className = "", style = {} }: NavItemProps) {
+  return (
+    <a
+      href={href}
+      onClick={onClick}
+      className={`sq-navitem ${className}`}
+      style={{
+        display: "flex",
+        alignItems: "center",
+        gap: "0.65rem",
+        padding: "0.5rem 0.75rem",
+        borderRadius: "var(--radius-sm)",
+        fontSize: "var(--text-sm)",
+        fontWeight: active ? "var(--weight-semibold)" : "var(--weight-medium)",
+        color: active ? "var(--text-strong)" : "var(--text-primary)",
+        background: active ? "var(--surface-hover)" : "transparent",
+        borderLeft: active ? "2px solid var(--brand-primary)" : "2px solid transparent",
+        textDecoration: "none",
+        ...style,
+      }}
+    >
+      {icon && <Icon name={icon} size={16} style={{ color: active ? "var(--brand-primary)" : "var(--text-secondary)" }} />}
+      {label}
+    </a>
+  );
+}
diff --git a/packages/dashboard/src/ui/Pagination.stories.tsx b/packages/dashboard/src/ui/Pagination.stories.tsx
new file mode 100644
index 0000000..c46482e
--- /dev/null
+++ b/packages/dashboard/src/ui/Pagination.stories.tsx
@@ -0,0 +1,18 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Pagination } from "./Pagination";
+
+const meta = {
+  title: "Data table/Pagination",
+  component: Pagination,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Pagination>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Middle: Story = { args: { page: 3, hasNext: true } };
+
+export const FirstPage: Story = { args: { page: 1, hasNext: true } };
+
+export const LastPage: Story = { args: { page: 9, hasNext: false } };
diff --git a/packages/dashboard/src/ui/Pagination.test.tsx b/packages/dashboard/src/ui/Pagination.test.tsx
new file mode 100644
index 0000000..93cea99
--- /dev/null
+++ b/packages/dashboard/src/ui/Pagination.test.tsx
@@ -0,0 +1,22 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { Pagination } from "./Pagination";
+
+describe("Pagination", () => {
+  it("enables both ends when there is a previous and next page", () => {
+    render(<Pagination page={2} hasNext />);
+
+    expect(screen.getByText("Page 2")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "«" })).toBeEnabled();
+    expect(screen.getByRole("button", { name: "»" })).toBeEnabled();
+  });
+
+  it("disables the ends on the first page with no next, and honors className/style", () => {
+    const onPrev = vi.fn();
+    const onNext = vi.fn();
+    render(<Pagination page={1} onPrev={onPrev} onNext={onNext} className="extra" style={{ opacity: 1 }} />);
+
+    expect(screen.getByRole("button", { name: "«" })).toBeDisabled();
+    expect(screen.getByRole("button", { name: "»" })).toBeDisabled();
+  });
+});
diff --git a/packages/dashboard/src/ui/Pagination.tsx b/packages/dashboard/src/ui/Pagination.tsx
new file mode 100644
index 0000000..35d93f8
--- /dev/null
+++ b/packages/dashboard/src/ui/Pagination.tsx
@@ -0,0 +1,51 @@
+import type { CSSProperties, ReactNode } from "react";
+
+/** Props for the {@link Pagination} control. */
+export interface PaginationProps {
+  page: number;
+  hasNext?: boolean;
+  onPrev?: () => void;
+  onNext?: () => void;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/**
+ * Pagination — the dashboard's joined prev / page / next control. Buttons abut with
+ * shared borders; the ends disable when there is no previous/next page.
+ */
+export function Pagination({ page, hasNext = false, onPrev, onNext, className = "", style = {} }: PaginationProps) {
+  const btn = (content: ReactNode, enabled: boolean, onClick: (() => void) | undefined, active: boolean) => (
+    <button
+      type="button"
+      disabled={!enabled}
+      onClick={enabled ? onClick : undefined}
+      style={{
+        height: "var(--control-height-sm)",
+        minWidth: "2rem",
+        padding: "0 0.7rem",
+        fontSize: "var(--text-xs)",
+        fontWeight: "var(--weight-medium)",
+        fontFamily: "var(--font-sans)",
+        color: active ? "var(--on-brand)" : "var(--text-primary)",
+        background: active ? "var(--brand-primary)" : "var(--surface-raised)",
+        border: "1px solid var(--border-strong)",
+        cursor: enabled ? "pointer" : "not-allowed",
+        opacity: enabled ? 1 : 0.4,
+      }}
+    >
+      {content}
+    </button>
+  );
+
+  return (
+    <div
+      className={`sq-pagination ${className}`}
+      style={{ display: "inline-flex", borderRadius: "var(--radius-sm)", overflow: "hidden", ...style }}
+    >
+      {btn("«", page > 1, onPrev, false)}
+      {btn(`Page ${page}`, false, undefined, true)}
+      {btn("»", hasNext, onNext, false)}
+    </div>
+  );
+}
diff --git a/packages/dashboard/src/ui/Select.stories.tsx b/packages/dashboard/src/ui/Select.stories.tsx
new file mode 100644
index 0000000..f2803cb
--- /dev/null
+++ b/packages/dashboard/src/ui/Select.stories.tsx
@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Select } from "./Select";
+
+const meta = {
+  title: "Forms/Select",
+  component: Select,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Select>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const States: Story = {
+  args: {
+    defaultValue: "running",
+    options: [
+      { value: "waiting", label: "Waiting" },
+      { value: "running", label: "Running" },
+      { value: "completed", label: "Completed" },
+      { value: "failed", label: "Failed" },
+    ],
+  },
+};
+
+export const Small: Story = {
+  args: {
+    size: "sm",
+    defaultValue: "default",
+    options: [
+      { value: "default", label: "default" },
+      { value: "mailers", label: "mailers" },
+    ],
+  },
+};
diff --git a/packages/dashboard/src/ui/Select.test.tsx b/packages/dashboard/src/ui/Select.test.tsx
new file mode 100644
index 0000000..591e839
--- /dev/null
+++ b/packages/dashboard/src/ui/Select.test.tsx
@@ -0,0 +1,35 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Select } from "./Select";
+
+describe("Select", () => {
+  it("renders options passed as data", () => {
+    render(
+      <Select
+        aria-label="status"
+        value="a"
+        onChange={() => undefined}
+        options={[
+          { value: "a", label: "Alpha" },
+          { value: "b", label: "Beta" },
+        ]}
+      />,
+    );
+
+    const select = screen.getByLabelText("status");
+    expect(select).toHaveClass("sq-select");
+    expect(screen.getByRole("option", { name: "Alpha" })).toBeInTheDocument();
+    expect(screen.getByRole("option", { name: "Beta" })).toBeInTheDocument();
+  });
+
+  it("renders option children and honors small size + className", () => {
+    render(
+      <Select aria-label="queue" size="sm" className="extra" defaultValue="c">
+        <option value="c">Gamma</option>
+      </Select>,
+    );
+
+    expect(screen.getByLabelText("queue")).toHaveClass("sq-select", "extra");
+    expect(screen.getByRole("option", { name: "Gamma" })).toBeInTheDocument();
+  });
+});
diff --git a/packages/dashboard/src/ui/Select.tsx b/packages/dashboard/src/ui/Select.tsx
new file mode 100644
index 0000000..5f3a541
--- /dev/null
+++ b/packages/dashboard/src/ui/Select.tsx
@@ -0,0 +1,59 @@
+import type { SelectHTMLAttributes } from "react";
+
+/** A single option for {@link Select} when passing data instead of children. */
+export interface SelectOption {
+  value: string;
+  label: string;
+}
+
+/** Props for the {@link Select} dropdown. Extends the native `select` attributes. */
+export interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, "size"> {
+  /** Options as data; alternatively pass `<option>` children. */
+  options?: SelectOption[];
+  /** @default "md" */
+  size?: "sm" | "md";
+}
+
+const CHEVRON =
+  "url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' fill='none' stroke='%239aa6ba' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m6 9 6 6 6-6'/%3E%3C/svg%3E\")";
+
+/**
+ * Select — native dropdown styled to match the dashboard's filter selects. Pass
+ * `options` as data, or `<option>` children.
+ */
+export function Select({ options, size = "md", className = "", style = {}, children, ...rest }: SelectProps) {
+  const height = size === "sm" ? "var(--control-height-sm)" : "var(--control-height)";
+  return (
+    <select
+      className={`sq-select ${className}`}
+      style={{
+        height,
+        width: "100%",
+        padding: "0 2rem 0 0.75rem",
+        fontFamily: "var(--font-sans)",
+        fontSize: "var(--text-sm)",
+        color: "var(--text-primary)",
+        background: "var(--surface-raised)",
+        border: "1px solid var(--border-strong)",
+        borderRadius: "var(--radius-sm)",
+        cursor: "pointer",
+        appearance: "none",
+        backgroundImage: CHEVRON,
+        backgroundRepeat: "no-repeat",
+        backgroundPosition: "right 0.6rem center",
+        transition:
+          "border-color var(--duration-fast) var(--ease-standard), box-shadow var(--duration-fast) var(--ease-standard)",
+        ...style,
+      }}
+      {...rest}
+    >
+      {options
+        ? options.map((o) => (
+            <option key={o.value} value={o.value}>
+              {o.label}
+            </option>
+          ))
+        : children}
+    </select>
+  );
+}
diff --git a/packages/dashboard/src/ui/Sidebar.stories.tsx b/packages/dashboard/src/ui/Sidebar.stories.tsx
new file mode 100644
index 0000000..deec42b
--- /dev/null
+++ b/packages/dashboard/src/ui/Sidebar.stories.tsx
@@ -0,0 +1,24 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { NavItem } from "./NavItem";
+import { Sidebar } from "./Sidebar";
+
+const meta = {
+  title: "Navigation/Sidebar",
+  component: Sidebar,
+} satisfies Meta<typeof Sidebar>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <div style={{ height: "26rem", display: "flex" }}>
+      <Sidebar>
+        <NavItem label="Dashboard" icon="layout-dashboard" active />
+        <NavItem label="Jobs" icon="list" />
+        <NavItem label="Queues" icon="layers" />
+      </Sidebar>
+    </div>
+  ),
+};
diff --git a/packages/dashboard/src/ui/Sidebar.test.tsx b/packages/dashboard/src/ui/Sidebar.test.tsx
new file mode 100644
index 0000000..f35a16f
--- /dev/null
+++ b/packages/dashboard/src/ui/Sidebar.test.tsx
@@ -0,0 +1,29 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Sidebar } from "./Sidebar";
+
+describe("Sidebar", () => {
+  it("renders the glyph fallback, default brand and footer", () => {
+    render(
+      <Sidebar>
+        <span>nav</span>
+      </Sidebar>,
+    );
+
+    expect(screen.getByText("Sidequest")).toBeInTheDocument();
+    expect(screen.getByText(/OSS Edition/)).toBeInTheDocument();
+  });
+
+  it("renders a logo image, custom brand, no footer, className and style", () => {
+    const { container } = render(
+      <Sidebar logoSrc="/logo.png" brand="Acme" footer={null} className="extra" style={{ opacity: 1 }}>
+        <span>nav</span>
+      </Sidebar>,
+    );
+
+    expect(container.querySelector(".sq-sidebar")).toHaveClass("extra");
+    expect(container.querySelector("img")).toHaveAttribute("src", "/logo.png");
+    expect(screen.getByText("Acme")).toBeInTheDocument();
+    expect(screen.queryByText(/OSS Edition/)).toBeNull();
+  });
+});
diff --git a/packages/dashboard/src/ui/Sidebar.tsx b/packages/dashboard/src/ui/Sidebar.tsx
new file mode 100644
index 0000000..dd4c633
--- /dev/null
+++ b/packages/dashboard/src/ui/Sidebar.tsx
@@ -0,0 +1,90 @@
+import type { CSSProperties, ReactNode } from "react";
+
+/** Props for the {@link Sidebar} app rail. */
+export interface SidebarProps {
+  /** Brand mark image src. Falls back to a glyph if omitted. */
+  logoSrc?: string;
+  /** Brand name. @default "Sidequest" */
+  brand?: string;
+  /** Footer text. @default "v0.1.0 · OSS Edition" */
+  footer?: ReactNode;
+  /** NavItem children. */
+  children?: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/**
+ * Sidebar — the dashboard's fixed left rail: brand lockup on top, nav in the middle,
+ * version footer at the bottom. Children are {@link NavItem}s.
+ */
+export function Sidebar({
+  logoSrc,
+  brand = "Sidequest",
+  footer = "v0.1.0 · OSS Edition",
+  children,
+  className = "",
+  style = {},
+}: SidebarProps) {
+  return (
+    <aside
+      className={`sq-sidebar ${className}`}
+      style={{
+        width: "var(--sidebar-width)",
+        flexShrink: 0,
+        display: "flex",
+        flexDirection: "column",
+        background: "var(--surface-card)",
+        borderRight: "1px solid var(--border-default)",
+        ...style,
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: "0.6rem",
+          padding: "var(--space-4)",
+          borderBottom: "1px solid var(--border-subtle)",
+        }}
+      >
+        {logoSrc ? (
+          <img src={logoSrc} alt="" style={{ height: 40, width: "auto" }} />
+        ) : (
+          <span
+            aria-hidden
+            style={{ fontFamily: "var(--font-brand)", fontSize: "var(--text-xl)", fontWeight: 600, color: "var(--text-strong)" }}
+          >
+            ◆
+          </span>
+        )}
+        <span
+          style={{
+            fontFamily: "var(--font-brand)",
+            fontSize: "var(--text-xl)",
+            fontWeight: "var(--weight-semibold)",
+            color: "var(--text-strong)",
+            letterSpacing: "-0.01em",
+          }}
+        >
+          {brand}
+        </span>
+      </div>
+      <nav style={{ flex: 1, padding: "var(--space-4)", display: "flex", flexDirection: "column", gap: "0.25rem" }}>
+        {children}
+      </nav>
+      {footer && (
+        <div
+          style={{
+            padding: "var(--space-4)",
+            borderTop: "1px solid var(--border-subtle)",
+            fontSize: "var(--text-xs)",
+            color: "var(--text-muted)",
+          }}
+        >
+          {footer}
+        </div>
+      )}
+    </aside>
+  );
+}
diff --git a/packages/dashboard/src/ui/StatCard.stories.tsx b/packages/dashboard/src/ui/StatCard.stories.tsx
new file mode 100644
index 0000000..6ac2386
--- /dev/null
+++ b/packages/dashboard/src/ui/StatCard.stories.tsx
@@ -0,0 +1,27 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { StatCard } from "./StatCard";
+
+const meta = {
+  title: "Data display/StatCard",
+  component: StatCard,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof StatCard>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Completed: Story = {
+  args: { label: "Completed", value: "1,284", tone: "completed", icon: "circle-check" },
+};
+
+export const Row: Story = {
+  render: () => (
+    <div style={{ display: "grid", gridTemplateColumns: "repeat(4, 1fr)", gap: "1rem" }}>
+      <StatCard label="Running" value={12} tone="running" icon="activity" />
+      <StatCard label="Completed" value="1,284" tone="completed" icon="circle-check" />
+      <StatCard label="Failed" value={7} tone="failed" icon="circle-x" delta="+2" />
+      <StatCard label="Scheduled" value={40} tone="scheduled" icon="clock" />
+    </div>
+  ),
+};
diff --git a/packages/dashboard/src/ui/StatCard.test.tsx b/packages/dashboard/src/ui/StatCard.test.tsx
new file mode 100644
index 0000000..f696fd7
--- /dev/null
+++ b/packages/dashboard/src/ui/StatCard.test.tsx
@@ -0,0 +1,23 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { StatCard } from "./StatCard";
+
+describe("StatCard", () => {
+  it("renders label and value with defaults (no icon, no delta)", () => {
+    const { container } = render(<StatCard label="Completed" value={42} />);
+
+    expect(screen.getByText("Completed")).toBeInTheDocument();
+    expect(screen.getByText("42")).toBeInTheDocument();
+    expect(container.querySelector("svg")).toBeNull();
+  });
+
+  it("renders a tone, icon, delta and className", () => {
+    const { container } = render(
+      <StatCard label="Failed" value={3} tone="failed" icon="activity" delta="+2 today" className="extra" style={{}} />,
+    );
+
+    expect(container.querySelector(".sq-statcard")).toHaveClass("extra");
+    expect(container.querySelector("svg")).not.toBeNull();
+    expect(screen.getByText("+2 today")).toBeInTheDocument();
+  });
+});
diff --git a/packages/dashboard/src/ui/StatCard.tsx b/packages/dashboard/src/ui/StatCard.tsx
new file mode 100644
index 0000000..a7fd086
--- /dev/null
+++ b/packages/dashboard/src/ui/StatCard.tsx
@@ -0,0 +1,60 @@
+import type { CSSProperties, ReactNode } from "react";
+import { Icon } from "./Icon";
+
+/** Number tone for {@link StatCard}. */
+export type StatTone = "running" | "completed" | "failed" | "scheduled" | "neutral";
+
+/** Props for the {@link StatCard} metric tile. */
+export interface StatCardProps {
+  /** Muted top label, e.g. "Completed Jobs". */
+  label: string;
+  /** Large number/value. */
+  value: ReactNode;
+  /** Number color. @default "neutral" */
+  tone?: StatTone;
+  /** Lucide icon in the top-right. */
+  icon?: string;
+  /** Small delta/subtext next to the value. */
+  delta?: string;
+  className?: string;
+  style?: CSSProperties;
+}
+
+const TONES: Record<StatTone, string> = {
+  running: "var(--status-running)",
+  completed: "var(--status-completed)",
+  failed: "var(--status-failed)",
+  scheduled: "var(--status-scheduled)",
+  neutral: "var(--text-strong)",
+};
+
+/**
+ * StatCard — the dashboard's top-row metric tile. Muted label, large tone-colored
+ * number, optional Lucide icon and delta.
+ */
+export function StatCard({ label, value, tone = "neutral", icon, delta, className = "", style = {} }: StatCardProps) {
+  return (
+    <div
+      className={`sq-statcard ${className}`}
+      style={{
+        background: "var(--surface-raised)",
+        border: "1px solid var(--border-default)",
+        borderRadius: "var(--radius-md)",
+        padding: "var(--space-4) var(--space-4)",
+        boxShadow: "var(--shadow-sm)",
+        ...style,
+      }}
+    >
+      <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between" }}>
+        <span style={{ fontSize: "var(--text-sm)", color: "var(--text-secondary)" }}>{label}</span>
+        {icon && <Icon name={icon} size={16} style={{ color: TONES[tone] }} />}
+      </div>
+      <div style={{ display: "flex", alignItems: "baseline", gap: "0.5rem", marginTop: "0.4rem" }}>
+        <span style={{ fontSize: "var(--text-3xl)", fontWeight: "var(--weight-bold)", color: TONES[tone], lineHeight: 1 }}>
+          {value}
+        </span>
+        {delta && <span style={{ fontSize: "var(--text-xs)", color: "var(--text-muted)" }}>{delta}</span>}
+      </div>
+    </div>
+  );
+}
diff --git a/packages/dashboard/src/ui/StepProgress.stories.tsx b/packages/dashboard/src/ui/StepProgress.stories.tsx
new file mode 100644
index 0000000..7a14bde
--- /dev/null
+++ b/packages/dashboard/src/ui/StepProgress.stories.tsx
@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { StepProgress } from "./StepProgress";
+
+const meta = {
+  title: "Data display/StepProgress",
+  component: StepProgress,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof StepProgress>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Completed: Story = {
+  args: {
+    steps: [
+      { label: "Enqueued", icon: "inbox", status: "done" },
+      { label: "Claimed", icon: "user-check", status: "done" },
+      { label: "Running", icon: "activity", status: "done" },
+      { label: "Completed", icon: "circle-check", status: "done" },
+    ],
+  },
+};
+
+export const Running: Story = {
+  args: {
+    steps: [
+      { label: "Enqueued", icon: "inbox", status: "done" },
+      { label: "Claimed", icon: "user-check", status: "done" },
+      { label: "Running", icon: "activity", status: "active" },
+      { label: "Completed", icon: "circle-check", status: "pending" },
+    ],
+  },
+};
+
+export const Failed: Story = {
+  args: {
+    steps: [
+      { label: "Enqueued", icon: "inbox", status: "done" },
+      { label: "Claimed", icon: "user-check", status: "done" },
+      { label: "Running", icon: "activity", status: "failed" },
+      { label: "Completed", icon: "circle-check", status: "canceled" },
+    ],
+  },
+};
diff --git a/packages/dashboard/src/ui/StepProgress.test.tsx b/packages/dashboard/src/ui/StepProgress.test.tsx
new file mode 100644
index 0000000..ba1f112
--- /dev/null
+++ b/packages/dashboard/src/ui/StepProgress.test.tsx
@@ -0,0 +1,26 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { StepProgress, type Step } from "./StepProgress";
+
+describe("StepProgress", () => {
+  it("renders a mixed-status timeline covering every node treatment", () => {
+    const steps: Step[] = [
+      { label: "Enqueued", icon: "inbox", status: "done" },
+      { label: "Claimed", status: "active" }, // no icon -> "circle"
+      { label: "Running", icon: "play", status: "pending" },
+      { label: "Failed", icon: "x", status: "failed" },
+    ];
+    render(<StepProgress steps={steps} />);
+
+    for (const s of steps) {
+      expect(screen.getByText(s.label)).toBeInTheDocument();
+    }
+  });
+
+  it("renders a single step (first and last) with className/style", () => {
+    render(<StepProgress steps={[{ label: "Only", status: "canceled" }]} className="extra" style={{ opacity: 1 }} />);
+
+    const root = screen.getByText("Only").closest(".sq-steps");
+    expect(root).toHaveClass("extra");
+  });
+});
diff --git a/packages/dashboard/src/ui/StepProgress.tsx b/packages/dashboard/src/ui/StepProgress.tsx
new file mode 100644
index 0000000..833c518
--- /dev/null
+++ b/packages/dashboard/src/ui/StepProgress.tsx
@@ -0,0 +1,95 @@
+import type { CSSProperties } from "react";
+import { Icon } from "./Icon";
+
+/** Status of a single {@link StepProgress} node. */
+export type StepStatus = "done" | "active" | "failed" | "canceled" | "pending";
+
+/** A single step in a {@link StepProgress} timeline. */
+export interface Step {
+  label: string;
+  /** Lucide icon name for the node. */
+  icon?: string;
+  status: StepStatus;
+}
+
+/** Props for the {@link StepProgress} lifecycle stepper. */
+export interface StepProgressProps {
+  steps: Step[];
+  className?: string;
+  style?: CSSProperties;
+}
+
+const STEP_TONE: Record<StepStatus, string> = {
+  done: "var(--status-completed)",
+  active: "var(--brand-primary)",
+  failed: "var(--status-failed)",
+  canceled: "var(--text-secondary)",
+  pending: "var(--border-strong)",
+};
+
+const FILLED: StepStatus[] = ["done", "active", "failed", "canceled"];
+
+/**
+ * StepProgress — the job-lifecycle stepper (Enqueued → Claimed → Running → Completed).
+ * Each step carries a label, an optional Lucide icon, and a status that drives its tone.
+ */
+export function StepProgress({ steps, className = "", style = {} }: StepProgressProps) {
+  return (
+    <div className={`sq-steps ${className}`} style={{ display: "flex", alignItems: "flex-start", width: "100%", ...style }}>
+      {steps.map((step, i) => {
+        const tone = STEP_TONE[step.status];
+        const isLast = i === steps.length - 1;
+        const nextTone = isLast ? null : STEP_TONE[steps[i + 1].status];
+        const lineTone =
+          step.status === "done"
+            ? "var(--status-completed)"
+            : nextTone && nextTone !== STEP_TONE.pending
+              ? tone
+              : "var(--border-default)";
+        const filled = FILLED.includes(step.status);
+        const leftLine =
+          i === 0
+            ? "transparent"
+            : steps[i - 1].status === "done"
+              ? "var(--status-completed)"
+              : filled
+                ? tone
+                : "var(--border-default)";
+        return (
+          <div key={i} style={{ display: "flex", flexDirection: "column", alignItems: "center", flex: 1 }}>
+            <div style={{ display: "flex", alignItems: "center", width: "100%" }}>
+              <div style={{ flex: 1, height: 3, background: leftLine }} />
+              <div
+                style={{
+                  width: 34,
+                  height: 34,
+                  flexShrink: 0,
+                  borderRadius: "var(--radius-full)",
+                  display: "flex",
+                  alignItems: "center",
+                  justifyContent: "center",
+                  background: filled ? tone : "var(--surface-raised)",
+                  border: filled ? "none" : "2px solid var(--border-strong)",
+                  color: filled ? "#fff" : "var(--text-muted)",
+                }}
+              >
+                <Icon name={step.icon ?? "circle"} size={16} />
+              </div>
+              <div style={{ flex: 1, height: 3, background: isLast ? "transparent" : lineTone }} />
+            </div>
+            <span
+              style={{
+                marginTop: "0.55rem",
+                fontSize: "var(--text-sm)",
+                color: filled ? "var(--text-primary)" : "var(--text-muted)",
+                fontWeight: "var(--weight-medium)",
+              }}
+            >
+              {step.label}
+            </span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/packages/dashboard/src/ui/Table.stories.tsx b/packages/dashboard/src/ui/Table.stories.tsx
new file mode 100644
index 0000000..33a0fdd
--- /dev/null
+++ b/packages/dashboard/src/ui/Table.stories.tsx
@@ -0,0 +1,30 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Badge } from "./Badge";
+import { type Column, Table } from "./Table";
+
+const meta = {
+  title: "Data table/Table",
+  component: Table,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Table>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const columns: Column[] = [
+  { key: "id", label: "ID", mono: true, width: "5rem" },
+  { key: "class", label: "Class" },
+  { key: "queue", label: "Queue" },
+  { key: "state", label: "State", render: (r) => <Badge state={r.state as never} /> },
+];
+
+const rows: Record<string, unknown>[] = [
+  { id: 1042, class: "SendEmailJob", queue: "mail", state: "completed" },
+  { id: 1043, class: "GenerateReportJob", queue: "heavy", state: "running" },
+  { id: 1044, class: "SendEmailJob", queue: "mail", state: "failed" },
+];
+
+export const Jobs: Story = { args: { columns, rows } };
+
+export const Empty: Story = { args: { columns, rows: [], empty: "No jobs match your filters." } };
diff --git a/packages/dashboard/src/ui/Table.test.tsx b/packages/dashboard/src/ui/Table.test.tsx
new file mode 100644
index 0000000..d3df182
--- /dev/null
+++ b/packages/dashboard/src/ui/Table.test.tsx
@@ -0,0 +1,41 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { type Column, Table } from "./Table";
+
+const columns: Column[] = [
+  { key: "id", label: "ID", mono: true },
+  { key: "name", label: "Name", align: "center", wrap: true, render: (r) => `#${String(r.name)}` },
+];
+
+describe("Table", () => {
+  it("renders rows, uses rowKey or index, custom render, and fires onRowClick", () => {
+    const rows: Record<string, unknown>[] = [{ id: 1, name: "a" }, { name: "b" }];
+    const onRowClick = vi.fn();
+    render(<Table columns={columns} rows={rows} onRowClick={onRowClick} />);
+
+    expect(screen.getByText("ID")).toBeInTheDocument();
+    expect(screen.getByText("#a")).toBeInTheDocument();
+    screen.getByText("#a").click();
+    expect(onRowClick).toHaveBeenCalledOnce();
+  });
+
+  it("renders plain cells without a click handler and honors rowKey/className/style", () => {
+    render(
+      <Table
+        columns={[{ key: "id", label: "ID" }]}
+        rows={[{ id: 5 }]}
+        rowKey="id"
+        className="extra"
+        style={{ opacity: 1 }}
+      />,
+    );
+
+    expect(screen.getByText("5")).toBeInTheDocument();
+  });
+
+  it("shows the empty state when there are no rows", () => {
+    render(<Table columns={columns} rows={[]} empty="Nothing here" />);
+
+    expect(screen.getByText("Nothing here")).toBeInTheDocument();
+  });
+});
diff --git a/packages/dashboard/src/ui/Table.tsx b/packages/dashboard/src/ui/Table.tsx
new file mode 100644
index 0000000..b2743ad
--- /dev/null
+++ b/packages/dashboard/src/ui/Table.tsx
@@ -0,0 +1,103 @@
+import type { CSSProperties, ReactNode } from "react";
+
+/** A column definition for {@link Table}. */
+export interface Column<Row = Record<string, unknown>> {
+  key: string;
+  label: ReactNode;
+  align?: "left" | "center" | "right";
+  width?: string;
+  /** Monospace cell (IDs, timestamps). */
+  mono?: boolean;
+  /** Allow wrapping (default: nowrap). */
+  wrap?: boolean;
+  /** Custom cell renderer. */
+  render?: (row: Row) => ReactNode;
+}
+
+/** Props for {@link Table}. */
+export interface TableProps<Row = Record<string, unknown>> {
+  columns: Column<Row>[];
+  rows: Row[];
+  /** Field used as React key. @default "id" */
+  rowKey?: string;
+  onRowClick?: (row: Row) => void;
+  /** Rendered when there are no rows. @default "No rows" */
+  empty?: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/**
+ * Table — dense dark data table for the jobs and queues lists. Columns describe cells
+ * (alignment, monospace, custom render); rows get a hover highlight and optional click.
+ */
+export function Table<Row extends Record<string, unknown> = Record<string, unknown>>({
+  columns,
+  rows,
+  rowKey = "id",
+  onRowClick,
+  empty = "No rows",
+  className = "",
+  style = {},
+}: TableProps<Row>) {
+  return (
+    <div style={{ overflowX: "auto", ...style }} className={className}>
+      <table style={{ width: "100%", borderCollapse: "collapse", fontSize: "var(--text-sm)" }}>
+        <thead>
+          <tr>
+            {columns.map((c) => (
+              <th
+                key={c.key}
+                style={{
+                  textAlign: c.align ?? "left",
+                  padding: "0.6rem 0.75rem",
+                  fontSize: "var(--text-xs)",
+                  fontWeight: "var(--weight-semibold)",
+                  color: "var(--text-secondary)",
+                  borderBottom: "1px solid var(--border-default)",
+                  whiteSpace: "nowrap",
+                  width: c.width,
+                }}
+              >
+                {c.label}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.length === 0 && (
+            <tr>
+              <td colSpan={columns.length} style={{ padding: "2rem", textAlign: "center", color: "var(--text-muted)" }}>
+                {empty}
+              </td>
+            </tr>
+          )}
+          {rows.map((row, i) => (
+            <tr
+              key={(row[rowKey] as string | number | undefined) ?? i}
+              className="sq-row"
+              onClick={onRowClick ? () => onRowClick(row) : undefined}
+              style={{ cursor: onRowClick ? "pointer" : "default" }}
+            >
+              {columns.map((c) => (
+                <td
+                  key={c.key}
+                  style={{
+                    textAlign: c.align ?? "left",
+                    padding: "0.65rem 0.75rem",
+                    color: "var(--text-primary)",
+                    borderBottom: "1px solid var(--border-subtle)",
+                    fontFamily: c.mono ? "var(--font-mono)" : "inherit",
+                    whiteSpace: c.wrap ? "normal" : "nowrap",
+                  }}
+                >
+                  {c.render ? c.render(row) : (row[c.key] as ReactNode)}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
diff --git a/packages/dashboard/src/ui/ThemeToggle.stories.tsx b/packages/dashboard/src/ui/ThemeToggle.stories.tsx
new file mode 100644
index 0000000..327325d
--- /dev/null
+++ b/packages/dashboard/src/ui/ThemeToggle.stories.tsx
@@ -0,0 +1,15 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { ThemeToggle } from "./ThemeToggle";
+
+const meta = {
+  title: "Actions/ThemeToggle",
+  component: ThemeToggle,
+} satisfies Meta<typeof ThemeToggle>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const Large: Story = { args: { size: "lg" } };
diff --git a/packages/dashboard/src/ui/ThemeToggle.test.tsx b/packages/dashboard/src/ui/ThemeToggle.test.tsx
new file mode 100644
index 0000000..95ea7b2
--- /dev/null
+++ b/packages/dashboard/src/ui/ThemeToggle.test.tsx
@@ -0,0 +1,77 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ThemeToggle } from "./ThemeToggle";
+
+function mockMatchMedia(matchesLight: boolean) {
+  vi.stubGlobal("matchMedia", vi.fn().mockReturnValue({ matches: matchesLight }));
+}
+
+beforeEach(() => {
+  document.documentElement.removeAttribute("data-theme");
+  localStorage.clear();
+  mockMatchMedia(false);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe("ThemeToggle", () => {
+  it("resolves an explicit light data-theme and toggles to dark, calling onChange", () => {
+    document.documentElement.setAttribute("data-theme", "light");
+    const onChange = vi.fn();
+    render(<ThemeToggle onChange={onChange} />);
+
+    const sw = screen.getByRole("switch");
+    expect(sw).toHaveAttribute("aria-checked", "true");
+    fireEvent.click(sw);
+    expect(onChange).toHaveBeenCalledWith("dark");
+    expect(sw).toHaveAttribute("aria-checked", "false");
+  });
+
+  it("resolves an explicit dark data-theme and toggles without onChange (sm size)", () => {
+    document.documentElement.setAttribute("data-theme", "dark");
+    render(<ThemeToggle size="sm" />);
+
+    const sw = screen.getByRole("switch");
+    expect(sw).toHaveAttribute("aria-checked", "false");
+    fireEvent.click(sw);
+    expect(sw).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("falls back to a persisted theme when no attribute is set", () => {
+    localStorage.setItem("sq-theme", "light");
+    render(<ThemeToggle />);
+    expect(screen.getByRole("switch")).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("falls back to the OS preference (light)", () => {
+    mockMatchMedia(true);
+    render(<ThemeToggle />);
+    expect(screen.getByRole("switch")).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("falls back to dark when nothing else applies", () => {
+    mockMatchMedia(false);
+    render(<ThemeToggle />);
+    expect(screen.getByRole("switch")).toHaveAttribute("aria-checked", "false");
+  });
+
+  it("survives localStorage.getItem throwing", () => {
+    vi.spyOn(Storage.prototype, "getItem").mockImplementation(() => {
+      throw new Error("blocked");
+    });
+    mockMatchMedia(true);
+    render(<ThemeToggle />);
+    expect(screen.getByRole("switch")).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("survives localStorage.setItem throwing", () => {
+    vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => {
+      throw new Error("blocked");
+    });
+    render(<ThemeToggle />);
+    expect(screen.getByRole("switch")).toBeInTheDocument();
+  });
+});
diff --git a/packages/dashboard/src/ui/ThemeToggle.tsx b/packages/dashboard/src/ui/ThemeToggle.tsx
new file mode 100644
index 0000000..04bc379
--- /dev/null
+++ b/packages/dashboard/src/ui/ThemeToggle.tsx
@@ -0,0 +1,113 @@
+import { type ButtonHTMLAttributes, useEffect, useState } from "react";
+import { Icon } from "./Icon";
+
+/** The two themes the design system ships. */
+export type Theme = "light" | "dark";
+/** Sizes for {@link ThemeToggle}. */
+export type ThemeToggleSize = "sm" | "md" | "lg";
+
+/** Props for {@link ThemeToggle}. */
+export interface ThemeToggleProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onChange"> {
+  /** @default "md" */
+  size?: ThemeToggleSize;
+  /** Called with the newly-applied theme after each toggle. */
+  onChange?: (theme: Theme) => void;
+}
+
+const STORAGE_KEY = "sq-theme";
+
+interface SizeSpec {
+  box: string;
+  icon: number;
+}
+
+const SIZES: Record<ThemeToggleSize, SizeSpec> = {
+  sm: { box: "var(--control-height-sm)", icon: 15 },
+  md: { box: "var(--control-height)", icon: 17 },
+  lg: { box: "2.75rem", icon: 19 },
+};
+
+function isTheme(value: string | null): value is Theme {
+  return value === "light" || value === "dark";
+}
+
+// First-paint theme: an explicit data-theme on <html> wins, then a persisted choice,
+// then the OS preference, else dark (the product default).
+function readInitial(): Theme {
+  const attr = document.documentElement.getAttribute("data-theme");
+  if (isTheme(attr)) {
+    return attr;
+  }
+  let saved: string | null = null;
+  try {
+    saved = localStorage.getItem(STORAGE_KEY);
+  } catch {
+    saved = null;
+  }
+  if (isTheme(saved)) {
+    return saved;
+  }
+  return window.matchMedia("(prefers-color-scheme: light)").matches ? "light" : "dark";
+}
+
+function applyTheme(theme: Theme): void {
+  document.documentElement.setAttribute("data-theme", theme);
+  try {
+    localStorage.setItem(STORAGE_KEY, theme);
+  } catch {
+    /* storage blocked */
+  }
+}
+
+/**
+ * ThemeToggle — flips the document between the dark (default) and light themes by
+ * setting `data-theme` on `<html>`, and persists the choice to localStorage. The
+ * sun/moon glyph reflects the theme it will switch TO.
+ */
+export function ThemeToggle({ size = "md", onChange, className = "", style = {}, ...rest }: ThemeToggleProps) {
+  const [theme, setTheme] = useState<Theme>(readInitial);
+  const s = SIZES[size];
+
+  useEffect(() => {
+    applyTheme(theme);
+  }, [theme]);
+
+  const isLight = theme === "light";
+
+  const toggle = () => {
+    const next: Theme = isLight ? "dark" : "light";
+    setTheme(next);
+    onChange?.(next);
+  };
+
+  return (
+    <button
+      type="button"
+      role="switch"
+      aria-checked={isLight}
+      aria-label={`Switch to ${isLight ? "dark" : "light"} theme`}
+      title={`Switch to ${isLight ? "dark" : "light"} theme`}
+      onClick={toggle}
+      className={`sq-btn sq-btn--default ${className}`}
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
+        width: s.box,
+        height: s.box,
+        padding: 0,
+        color: "var(--text-primary)",
+        background: "var(--surface-raised)",
+        border: "1px solid var(--border-strong)",
+        borderRadius: "var(--radius-sm)",
+        cursor: "pointer",
+        transition:
+          "background var(--duration-fast) var(--ease-standard), border-color var(--duration-fast) var(--ease-standard), color var(--duration-fast) var(--ease-standard)",
+        ...style,
+      }}
+      {...rest}
+    >
+      <Icon name={isLight ? "moon" : "sun"} size={s.icon} />
+    </button>
+  );
+}
diff --git a/packages/dashboard/src/ui/index.ts b/packages/dashboard/src/ui/index.ts
index 6e07bb4..ef1604c 100644
--- a/packages/dashboard/src/ui/index.ts
+++ b/packages/dashboard/src/ui/index.ts
@@ -1,8 +1,30 @@
-export { Card } from "./Card";
-export type { CardProps } from "./Card";
 export { Badge } from "./Badge";
 export type { BadgeProps, JobState, QueueState } from "./Badge";
-export { Icon } from "./Icon";
-export type { IconProps } from "./Icon";
 export { Button } from "./Button";
 export type { ButtonProps, ButtonSize, ButtonVariant } from "./Button";
+export { Card } from "./Card";
+export type { CardProps } from "./Card";
+export { CodeBlock } from "./CodeBlock";
+export type { CodeBlockProps } from "./CodeBlock";
+export { FormField } from "./FormField";
+export type { FormFieldProps } from "./FormField";
+export { Icon } from "./Icon";
+export type { IconProps } from "./Icon";
+export { Input } from "./Input";
+export type { InputProps } from "./Input";
+export { NavItem } from "./NavItem";
+export type { NavItemProps } from "./NavItem";
+export { Pagination } from "./Pagination";
+export type { PaginationProps } from "./Pagination";
+export { Select } from "./Select";
+export type { SelectOption, SelectProps } from "./Select";
+export { Sidebar } from "./Sidebar";
+export type { SidebarProps } from "./Sidebar";
+export { StatCard } from "./StatCard";
+export type { StatCardProps, StatTone } from "./StatCard";
+export { StepProgress } from "./StepProgress";
+export type { Step, StepProgressProps, StepStatus } from "./StepProgress";
+export { Table } from "./Table";
+export type { Column, TableProps } from "./Table";
+export { ThemeToggle } from "./ThemeToggle";
+export type { Theme, ThemeToggleProps, ThemeToggleSize } from "./ThemeToggle";

From 518b009eeb4d5e1196aa971a035972e1326e8c80 Mon Sep 17 00:00:00 2001
From: merencia <lucas.merencia@gmail.com>
Date: Fri, 3 Jul 2026 20:54:20 -0300
Subject: [PATCH 4/7] fix(dashboard): make Badge theme-aware and fix CodeBlock
 text in light theme

Badge status colors now come from the theme-aware --status-* tokens with a color-mix fill, so pills stay legible in the light theme instead of washing out. CodeBlock text uses a fixed light color since the code surface is always near-black in both themes.
---
 packages/dashboard/src/ui/Badge.test.tsx |  2 +-
 packages/dashboard/src/ui/Badge.tsx      | 37 +++++++++++++-----------
 packages/dashboard/src/ui/CodeBlock.tsx  |  4 ++-
 3 files changed, 24 insertions(+), 19 deletions(-)

diff --git a/packages/dashboard/src/ui/Badge.test.tsx b/packages/dashboard/src/ui/Badge.test.tsx
index f0e94a6..51635b5 100644
--- a/packages/dashboard/src/ui/Badge.test.tsx
+++ b/packages/dashboard/src/ui/Badge.test.tsx
@@ -8,7 +8,7 @@ describe("Badge", () => {
 
     const el = container.querySelector(".sq-badge");
     expect(el).toHaveTextContent("Completed");
-    expect(el).toHaveStyle({ color: "#7bd6a0" });
+    expect(el).toHaveStyle({ color: "var(--status-completed)" });
     // no dot by default
     expect(el?.querySelector("span")).toBeNull();
   });
diff --git a/packages/dashboard/src/ui/Badge.tsx b/packages/dashboard/src/ui/Badge.tsx
index 62f5618..718a9cc 100644
--- a/packages/dashboard/src/ui/Badge.tsx
+++ b/packages/dashboard/src/ui/Badge.tsx
@@ -21,32 +21,35 @@ export interface BadgeProps {
 }
 
 interface StatePreset {
-  bg: string;
-  fg: string;
+  /** Theme-aware status color token; the pill fill is a soft tint of it. */
+  color: string;
   label: string;
 }
 
 const STATE: Record<string, StatePreset> = {
-  completed: { bg: "rgba(79,175,117,0.18)", fg: "#7bd6a0", label: "Completed" },
-  failed: { bg: "rgba(183,82,82,0.20)", fg: "#e88d8d", label: "Failed" },
-  running: { bg: "rgba(43,124,211,0.20)", fg: "#71b0f2", label: "Running" },
-  claimed: { bg: "rgba(61,125,216,0.18)", fg: "#6fa8ec", label: "Claimed" },
-  waiting: { bg: "rgba(210,169,76,0.18)", fg: "#e0c078", label: "Waiting" },
-  scheduled: { bg: "rgba(210,169,76,0.18)", fg: "#e0c078", label: "Scheduled" },
-  canceled: { bg: "rgba(154,166,186,0.16)", fg: "#b3bdcc", label: "Canceled" },
-  active: { bg: "rgba(79,175,117,0.18)", fg: "#7bd6a0", label: "Active" },
-  paused: { bg: "rgba(210,169,76,0.18)", fg: "#e0c078", label: "Paused" },
-  disabled: { bg: "rgba(183,82,82,0.20)", fg: "#e88d8d", label: "Disabled" },
-  neutral: { bg: "var(--surface-hover)", fg: "var(--text-secondary)", label: "" },
+  completed: { color: "var(--status-completed)", label: "Completed" },
+  failed: { color: "var(--status-failed)", label: "Failed" },
+  running: { color: "var(--status-running)", label: "Running" },
+  claimed: { color: "var(--status-running)", label: "Claimed" },
+  waiting: { color: "var(--status-scheduled)", label: "Waiting" },
+  scheduled: { color: "var(--status-scheduled)", label: "Scheduled" },
+  canceled: { color: "var(--text-secondary)", label: "Canceled" },
+  active: { color: "var(--status-completed)", label: "Active" },
+  paused: { color: "var(--status-scheduled)", label: "Paused" },
+  disabled: { color: "var(--status-failed)", label: "Disabled" },
+  neutral: { color: "var(--text-secondary)", label: "" },
 };
 
 /**
  * Badge — soft-filled status pill. Presets cover every Sidequest job state
  * (completed/failed/running/claimed/waiting/scheduled/canceled) and queue state
- * (active/paused/disabled). Pass `state` for a preset or `bg`/`fg` to override.
+ * (active/paused/disabled). Colors come from the theme-aware status tokens, so the
+ * pill adapts to the light and dark themes; pass `bg`/`fg` to override.
  */
 export function Badge({ state = "neutral", children, dot = false, className = "", style = {}, bg, fg }: BadgeProps) {
-  const preset = STATE[state] || STATE.neutral;
+  const preset = STATE[state] ?? STATE.neutral;
+  const foreground = fg ?? preset.color;
+  const background = bg ?? `color-mix(in srgb, ${preset.color} 18%, transparent)`;
   return (
     <span
       className={`sq-badge ${className}`}
@@ -60,8 +63,8 @@ export function Badge({ state = "neutral", children, dot = false, className = ""
         fontWeight: "var(--weight-semibold)",
         lineHeight: 1,
         borderRadius: "var(--radius-full)",
-        background: bg ?? preset.bg,
-        color: fg ?? preset.fg,
+        background,
+        color: foreground,
         whiteSpace: "nowrap",
         ...style,
       }}
diff --git a/packages/dashboard/src/ui/CodeBlock.tsx b/packages/dashboard/src/ui/CodeBlock.tsx
index 1bae134..15bec18 100644
--- a/packages/dashboard/src/ui/CodeBlock.tsx
+++ b/packages/dashboard/src/ui/CodeBlock.tsx
@@ -29,7 +29,9 @@ export function CodeBlock({ code, language, maxHeight = "15rem", className = "",
         fontFamily: "var(--font-mono)",
         fontSize: "var(--text-xs)",
         lineHeight: 1.6,
-        color: "var(--text-primary)",
+        // The code surface is always near-black (terminal-style) in both themes, so the
+        // text stays light regardless of the active theme.
+        color: "var(--sq-gray-300)",
         maxHeight,
         overflow: "auto",
         ...style,

From 1a514ee752e5fb89cefd1a8951b1cff92f30173b Mon Sep 17 00:00:00 2001
From: merencia <lucas.merencia@gmail.com>
Date: Fri, 3 Jul 2026 21:02:42 -0300
Subject: [PATCH 5/7] fix(dashboard): light code surface in light theme

the code block surface now adapts: near-black in dark, light gray in light, with theme-aware text on top. reverts the always-dark-surface assumption.
---
 packages/dashboard/src/ui/CodeBlock.tsx     | 4 +---
 packages/dashboard/src/ui/tokens/colors.css | 2 +-
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/packages/dashboard/src/ui/CodeBlock.tsx b/packages/dashboard/src/ui/CodeBlock.tsx
index 15bec18..1bae134 100644
--- a/packages/dashboard/src/ui/CodeBlock.tsx
+++ b/packages/dashboard/src/ui/CodeBlock.tsx
@@ -29,9 +29,7 @@ export function CodeBlock({ code, language, maxHeight = "15rem", className = "",
         fontFamily: "var(--font-mono)",
         fontSize: "var(--text-xs)",
         lineHeight: 1.6,
-        // The code surface is always near-black (terminal-style) in both themes, so the
-        // text stays light regardless of the active theme.
-        color: "var(--sq-gray-300)",
+        color: "var(--text-primary)",
         maxHeight,
         overflow: "auto",
         ...style,
diff --git a/packages/dashboard/src/ui/tokens/colors.css b/packages/dashboard/src/ui/tokens/colors.css
index ef10671..3eb0b36 100644
--- a/packages/dashboard/src/ui/tokens/colors.css
+++ b/packages/dashboard/src/ui/tokens/colors.css
@@ -108,7 +108,7 @@
   --surface-raised:   #ffffff;
   --surface-card:     #ffffff;
   --surface-hover:    var(--sq-gray-100);
-  --surface-code:     #0b0f1a;
+  --surface-code:     var(--sq-gray-100);
   --surface-inset:    var(--sq-gray-100);
 
   --text-primary:     #1f2739;

From bbf04c47698c9967c67d62d5ddd45d8112d89d9f Mon Sep 17 00:00:00 2001
From: merencia <lucas.merencia@gmail.com>
Date: Sat, 4 Jul 2026 21:15:53 -0300
Subject: [PATCH 6/7] refactor(dashboard): style ui components with tailwind +
 tokens

the ui components were authored with inline style objects. this reworks
them to tailwind v4 utilities that read from the design tokens, dropping
daisyui from the mix. styles.css bridges the token css vars into tailwind
via `@theme inline` (kept inline so the semantic colors stay theme-aware),
the shipped stylesheet is now compiled by the tailwind cli, and the sq-*
class names stay on the elements as styling hooks. behavior, props and the
public api are unchanged.
---
 packages/dashboard/package.json            |   3 +-
 packages/dashboard/src/ui/Badge.test.tsx   |   4 +-
 packages/dashboard/src/ui/Badge.tsx        |  64 ++++++-------
 packages/dashboard/src/ui/Button.test.tsx  |  18 ++++
 packages/dashboard/src/ui/Button.tsx       |  83 ++++++----------
 packages/dashboard/src/ui/Card.tsx         |  38 ++------
 packages/dashboard/src/ui/CodeBlock.tsx    |  21 ++---
 packages/dashboard/src/ui/FormField.tsx    |  13 +--
 packages/dashboard/src/ui/Input.tsx        |  25 ++---
 packages/dashboard/src/ui/NavItem.tsx      |  28 +++---
 packages/dashboard/src/ui/Pagination.tsx   |  24 ++---
 packages/dashboard/src/ui/Select.tsx       |  65 ++++++-------
 packages/dashboard/src/ui/Sidebar.tsx      |  59 ++----------
 packages/dashboard/src/ui/StatCard.tsx     |  38 +++-----
 packages/dashboard/src/ui/StepProgress.tsx |  73 ++++++---------
 packages/dashboard/src/ui/Table.tsx        |  48 +++++-----
 packages/dashboard/src/ui/ThemeToggle.tsx  |  38 +++-----
 packages/dashboard/src/ui/cn.ts            |  10 ++
 packages/dashboard/src/ui/styles.css       | 104 ++++++++++++++++++++-
 packages/dashboard/src/ui/tokens/base.css  |  20 +---
 packages/dashboard/vite.lib.config.ts      |  21 +----
 yarn.lock                                  |  10 ++
 22 files changed, 373 insertions(+), 434 deletions(-)
 create mode 100644 packages/dashboard/src/ui/cn.ts

diff --git a/packages/dashboard/package.json b/packages/dashboard/package.json
index e6d102d..40134b8 100644
--- a/packages/dashboard/package.json
+++ b/packages/dashboard/package.json
@@ -43,7 +43,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "npx rollup -c && npx vite build --config vite.lib.config.ts",
+    "build": "npx rollup -c && npx vite build --config vite.lib.config.ts && npx @tailwindcss/cli -i ./src/ui/styles.css -o ./dist/ui/styles.css --minify",
     "dev": "npx rollup -c -w",
     "test": "yarn vitest run",
     "storybook": "storybook dev -p 6006",
@@ -54,6 +54,7 @@
     "@sidequest/backend": "workspace:*",
     "@sidequest/core": "workspace:*",
     "@sidequest/engine": "workspace:*",
+    "clsx": "^2.1.1",
     "ejs": "^4.0.1",
     "express": "^5.2.1",
     "express-basic-auth": "^1.2.1",
diff --git a/packages/dashboard/src/ui/Badge.test.tsx b/packages/dashboard/src/ui/Badge.test.tsx
index 51635b5..b8039dd 100644
--- a/packages/dashboard/src/ui/Badge.test.tsx
+++ b/packages/dashboard/src/ui/Badge.test.tsx
@@ -8,7 +8,7 @@ describe("Badge", () => {
 
     const el = container.querySelector(".sq-badge");
     expect(el).toHaveTextContent("Completed");
-    expect(el).toHaveStyle({ color: "var(--status-completed)" });
+    expect(el).toHaveClass("text-status-completed", "bg-status-completed/15");
     // no dot by default
     expect(el?.querySelector("span")).toBeNull();
   });
@@ -34,6 +34,6 @@ describe("Badge", () => {
     const el = container.querySelector(".sq-badge");
     // neutral label is empty
     expect(el).toHaveTextContent("");
-    expect(el).toHaveStyle({ color: "var(--text-secondary)" });
+    expect(el).toHaveClass("text-fg-secondary", "bg-fg-secondary/15");
   });
 });
diff --git a/packages/dashboard/src/ui/Badge.tsx b/packages/dashboard/src/ui/Badge.tsx
index 718a9cc..b1dc51e 100644
--- a/packages/dashboard/src/ui/Badge.tsx
+++ b/packages/dashboard/src/ui/Badge.tsx
@@ -1,4 +1,5 @@
 import type { CSSProperties, ReactNode } from "react";
+import { cn } from "./cn";
 
 /** Job lifecycle states with a badge preset. */
 export type JobState = "completed" | "failed" | "running" | "claimed" | "waiting" | "scheduled" | "canceled";
@@ -11,9 +12,9 @@ export interface BadgeProps {
   state?: JobState | QueueState | "neutral";
   /** Show a leading status dot. */
   dot?: boolean;
-  /** Override background. */
+  /** Override background (caller escape hatch, applied inline). */
   bg?: string;
-  /** Override foreground. */
+  /** Override foreground (caller escape hatch, applied inline). */
   fg?: string;
   children?: ReactNode;
   className?: string;
@@ -21,23 +22,25 @@ export interface BadgeProps {
 }
 
 interface StatePreset {
-  /** Theme-aware status color token; the pill fill is a soft tint of it. */
-  color: string;
+  /** Foreground text utility (theme-aware status token). */
+  text: string;
+  /** Soft-tint fill utility (same token at low alpha). */
+  fill: string;
   label: string;
 }
 
 const STATE: Record<string, StatePreset> = {
-  completed: { color: "var(--status-completed)", label: "Completed" },
-  failed: { color: "var(--status-failed)", label: "Failed" },
-  running: { color: "var(--status-running)", label: "Running" },
-  claimed: { color: "var(--status-running)", label: "Claimed" },
-  waiting: { color: "var(--status-scheduled)", label: "Waiting" },
-  scheduled: { color: "var(--status-scheduled)", label: "Scheduled" },
-  canceled: { color: "var(--text-secondary)", label: "Canceled" },
-  active: { color: "var(--status-completed)", label: "Active" },
-  paused: { color: "var(--status-scheduled)", label: "Paused" },
-  disabled: { color: "var(--status-failed)", label: "Disabled" },
-  neutral: { color: "var(--text-secondary)", label: "" },
+  completed: { text: "text-status-completed", fill: "bg-status-completed/15", label: "Completed" },
+  failed: { text: "text-status-failed", fill: "bg-status-failed/15", label: "Failed" },
+  running: { text: "text-status-running", fill: "bg-status-running/15", label: "Running" },
+  claimed: { text: "text-status-running", fill: "bg-status-running/15", label: "Claimed" },
+  waiting: { text: "text-status-scheduled", fill: "bg-status-scheduled/15", label: "Waiting" },
+  scheduled: { text: "text-status-scheduled", fill: "bg-status-scheduled/15", label: "Scheduled" },
+  canceled: { text: "text-fg-secondary", fill: "bg-fg-secondary/15", label: "Canceled" },
+  active: { text: "text-status-completed", fill: "bg-status-completed/15", label: "Active" },
+  paused: { text: "text-status-scheduled", fill: "bg-status-scheduled/15", label: "Paused" },
+  disabled: { text: "text-status-failed", fill: "bg-status-failed/15", label: "Disabled" },
+  neutral: { text: "text-fg-secondary", fill: "bg-fg-secondary/15", label: "" },
 };
 
 /**
@@ -48,28 +51,21 @@ const STATE: Record<string, StatePreset> = {
  */
 export function Badge({ state = "neutral", children, dot = false, className = "", style = {}, bg, fg }: BadgeProps) {
   const preset = STATE[state] ?? STATE.neutral;
-  const foreground = fg ?? preset.color;
-  const background = bg ?? `color-mix(in srgb, ${preset.color} 18%, transparent)`;
+  const override: CSSProperties = {};
+  if (bg) override.background = bg;
+  if (fg) override.color = fg;
+
   return (
     <span
-      className={`sq-badge ${className}`}
-      style={{
-        display: "inline-flex",
-        alignItems: "center",
-        gap: "0.35rem",
-        height: "1.5rem",
-        padding: "0 0.6rem",
-        fontSize: "var(--text-xs)",
-        fontWeight: "var(--weight-semibold)",
-        lineHeight: 1,
-        borderRadius: "var(--radius-full)",
-        background,
-        color: foreground,
-        whiteSpace: "nowrap",
-        ...style,
-      }}
+      className={cn(
+        "sq-badge inline-flex items-center gap-[0.35rem] h-6 px-[0.6rem] text-xs font-semibold leading-none rounded-full whitespace-nowrap",
+        !fg && preset.text,
+        !bg && preset.fill,
+        className,
+      )}
+      style={{ ...override, ...style }}
     >
-      {dot && <span style={{ width: 6, height: 6, borderRadius: "var(--radius-full)", background: "currentColor" }} />}
+      {dot && <span className="w-1.5 h-1.5 rounded-full bg-current" />}
       {children ?? preset.label}
     </span>
   );
diff --git a/packages/dashboard/src/ui/Button.test.tsx b/packages/dashboard/src/ui/Button.test.tsx
index 239ace5..eb5ed92 100644
--- a/packages/dashboard/src/ui/Button.test.tsx
+++ b/packages/dashboard/src/ui/Button.test.tsx
@@ -38,4 +38,22 @@ describe("Button", () => {
     // leading + trailing icons
     expect(btn.querySelectorAll("svg")).toHaveLength(2);
   });
+
+  it("fills the default and ghost variants with the hover surface when active", () => {
+    const { rerender } = render(
+      <Button variant="default" active>
+        D
+      </Button>,
+    );
+    const def = screen.getByRole("button", { name: "D" });
+    expect(def).toHaveClass("bg-surface-hover");
+    expect(def).not.toHaveClass("bg-surface-raised");
+
+    rerender(
+      <Button variant="ghost" active>
+        G
+      </Button>,
+    );
+    expect(screen.getByRole("button", { name: "G" })).toHaveClass("bg-surface-hover");
+  });
 });
diff --git a/packages/dashboard/src/ui/Button.tsx b/packages/dashboard/src/ui/Button.tsx
index 4c9feab..483514c 100644
--- a/packages/dashboard/src/ui/Button.tsx
+++ b/packages/dashboard/src/ui/Button.tsx
@@ -1,4 +1,5 @@
-import type { ButtonHTMLAttributes, CSSProperties } from "react";
+import type { ButtonHTMLAttributes } from "react";
+import { cn } from "./cn";
 import { Icon } from "./Icon";
 
 /** Visual treatments for {@link Button}. */
@@ -22,18 +23,22 @@ export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   active?: boolean;
 }
 
-interface SizeSpec {
-  height: string;
-  padding: string;
-  font: string;
-  gap: string;
-  icon: number;
-}
+const BASE =
+  "inline-flex items-center justify-center whitespace-nowrap select-none font-sans font-medium leading-none rounded-sm border border-transparent cursor-pointer transition-[background-color,border-color,transform] duration-[120ms] ease-standard disabled:opacity-50 disabled:cursor-not-allowed enabled:active:translate-y-[0.5px] focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-brand-ring";
+
+const SIZES: Record<ButtonSize, { class: string; icon: number }> = {
+  sm: { class: "h-control-sm px-[0.7rem] gap-[0.35rem] text-xs", icon: 14 },
+  md: { class: "h-control px-4 gap-[0.45rem] text-sm", icon: 16 },
+  lg: { class: "h-11 px-[1.35rem] gap-2 text-base", icon: 18 },
+};
 
-const SIZES: Record<ButtonSize, SizeSpec> = {
-  sm: { height: "var(--control-height-sm)", padding: "0 0.7rem", font: "var(--text-xs)", gap: "0.35rem", icon: 14 },
-  md: { height: "var(--control-height)", padding: "0 1rem", font: "var(--text-sm)", gap: "0.45rem", icon: 16 },
-  lg: { height: "2.75rem", padding: "0 1.35rem", font: "var(--text-base)", gap: "0.5rem", icon: 18 },
+const VARIANTS: Record<ButtonVariant, string> = {
+  primary: "bg-brand text-on-brand border-brand enabled:hover:bg-brand-hover enabled:hover:border-brand-hover",
+  default: "text-fg border-edge-strong enabled:hover:bg-surface-hover",
+  outline: "bg-transparent text-fg border-edge-strong enabled:hover:bg-surface-hover",
+  ghost: "text-fg border-transparent enabled:hover:bg-surface-hover",
+  danger:
+    "bg-transparent text-status-failed border-edge-strong enabled:hover:bg-status-failed/10 enabled:hover:border-status-failed",
 };
 
 /**
@@ -52,55 +57,27 @@ export function Button({
   active = false,
   type = "button",
   className = "",
-  style = {},
   ...rest
 }: ButtonProps) {
   const s = SIZES[size];
-
-  const base: CSSProperties = {
-    display: block ? "flex" : "inline-flex",
-    width: block ? "100%" : "auto",
-    alignItems: "center",
-    justifyContent: "center",
-    gap: s.gap,
-    height: s.height,
-    padding: s.padding,
-    fontFamily: "var(--font-sans)",
-    fontSize: s.font,
-    fontWeight: "var(--weight-medium)",
-    lineHeight: 1,
-    whiteSpace: "nowrap",
-    borderRadius: "var(--radius-sm)",
-    border: "1px solid transparent",
-    cursor: disabled ? "not-allowed" : "pointer",
-    opacity: disabled ? 0.5 : 1,
-    transition:
-      "background var(--duration-fast) var(--ease-standard), border-color var(--duration-fast) var(--ease-standard), transform var(--duration-fast) var(--ease-standard)",
-    userSelect: "none",
-  };
-
-  const variants: Record<ButtonVariant, CSSProperties> = {
-    primary: { background: "var(--brand-primary)", color: "var(--on-brand)", borderColor: "var(--brand-primary)" },
-    default: {
-      background: active ? "var(--surface-hover)" : "var(--surface-raised)",
-      color: "var(--text-primary)",
-      borderColor: "var(--border-strong)",
-    },
-    outline: { background: "transparent", color: "var(--text-primary)", borderColor: "var(--border-strong)" },
-    ghost: {
-      background: active ? "var(--surface-hover)" : "transparent",
-      color: "var(--text-primary)",
-      borderColor: "transparent",
-    },
-    danger: { background: "transparent", color: "var(--status-failed)", borderColor: "var(--border-strong)" },
-  };
+  // `active` fills default/ghost with the hover surface to read as pressed/selected.
+  const activeFill = active && (variant === "default" || variant === "ghost") ? "bg-surface-hover" : "";
+  const defaultRaised = variant === "default" && !active ? "bg-surface-raised" : "";
 
   return (
     <button
       type={type}
       disabled={disabled}
-      className={`sq-btn sq-btn--${variant} ${className}`}
-      style={{ ...base, ...variants[variant], ...style }}
+      className={cn(
+        `sq-btn sq-btn--${variant}`,
+        BASE,
+        s.class,
+        VARIANTS[variant],
+        defaultRaised,
+        activeFill,
+        block ? "flex w-full" : "inline-flex w-auto",
+        className,
+      )}
       {...rest}
     >
       {icon && <Icon name={icon} size={s.icon} />}
diff --git a/packages/dashboard/src/ui/Card.tsx b/packages/dashboard/src/ui/Card.tsx
index 2e3a109..002b4ab 100644
--- a/packages/dashboard/src/ui/Card.tsx
+++ b/packages/dashboard/src/ui/Card.tsx
@@ -1,4 +1,5 @@
 import type { CSSProperties, ReactNode } from "react";
+import { cn } from "./cn";
 
 /** Props for the {@link Card} panel primitive. */
 export interface CardProps {
@@ -6,7 +7,7 @@ export interface CardProps {
   title?: ReactNode;
   /** Right-aligned header actions (buttons). */
   actions?: ReactNode;
-  /** Body padding. @default "var(--space-6)" */
+  /** Body padding (CSS length). @default "var(--space-6)" */
   padding?: string;
   children?: ReactNode;
   className?: string;
@@ -29,39 +30,16 @@ export function Card({
 }: CardProps) {
   return (
     <div
-      className={`sq-card ${className}`}
-      style={{
-        background: "var(--surface-card)",
-        border: "1px solid var(--border-default)",
-        borderRadius: "var(--radius-md)",
-        boxShadow: "var(--shadow-md)",
-        overflow: "hidden",
-        ...style,
-      }}
+      className={cn("sq-card overflow-hidden bg-surface-card border border-edge rounded-md shadow-md", className)}
+      style={style}
     >
       {(title != null || actions != null) && (
         <div
-          style={{
-            display: "flex",
-            alignItems: "center",
-            justifyContent: "space-between",
-            padding: `var(--space-4) ${padding}`,
-            borderBottom: "1px solid var(--border-subtle)",
-          }}
+          className="flex items-center justify-between border-b border-edge-subtle"
+          style={{ padding: `var(--space-4) ${padding}` }}
         >
-          {title && (
-            <h3
-              style={{
-                margin: 0,
-                fontSize: "var(--text-lg)",
-                fontWeight: "var(--weight-semibold)",
-                color: "var(--text-strong)",
-              }}
-            >
-              {title}
-            </h3>
-          )}
-          {actions && <div style={{ display: "flex", gap: "0.5rem" }}>{actions}</div>}
+          {title && <h3 className="m-0 text-lg font-semibold text-fg-strong">{title}</h3>}
+          {actions && <div className="flex gap-2">{actions}</div>}
         </div>
       )}
       <div style={{ padding, ...bodyStyle }}>{children}</div>
diff --git a/packages/dashboard/src/ui/CodeBlock.tsx b/packages/dashboard/src/ui/CodeBlock.tsx
index 1bae134..56f39c6 100644
--- a/packages/dashboard/src/ui/CodeBlock.tsx
+++ b/packages/dashboard/src/ui/CodeBlock.tsx
@@ -1,4 +1,5 @@
 import type { CSSProperties } from "react";
+import { cn } from "./cn";
 
 /** Props for the {@link CodeBlock} monospace panel. */
 export interface CodeBlockProps {
@@ -19,21 +20,11 @@ export function CodeBlock({ code, language, maxHeight = "15rem", className = "",
   const text = typeof code === "string" ? code : JSON.stringify(code, null, 2);
   return (
     <pre
-      className={`sq-codeblock ${className}`}
-      style={{
-        margin: 0,
-        background: "var(--surface-code)",
-        border: "1px solid var(--border-default)",
-        borderRadius: "var(--radius-md)",
-        padding: "0.85rem 1rem",
-        fontFamily: "var(--font-mono)",
-        fontSize: "var(--text-xs)",
-        lineHeight: 1.6,
-        color: "var(--text-primary)",
-        maxHeight,
-        overflow: "auto",
-        ...style,
-      }}
+      className={cn(
+        "sq-codeblock m-0 bg-surface-code border border-edge rounded-md px-4 py-[0.85rem] font-mono text-xs leading-[1.6] text-fg overflow-auto",
+        className,
+      )}
+      style={{ maxHeight, ...style }}
     >
       <code data-language={language}>{text}</code>
     </pre>
diff --git a/packages/dashboard/src/ui/FormField.tsx b/packages/dashboard/src/ui/FormField.tsx
index 55b8e81..d19ce80 100644
--- a/packages/dashboard/src/ui/FormField.tsx
+++ b/packages/dashboard/src/ui/FormField.tsx
@@ -1,4 +1,5 @@
 import type { CSSProperties, ReactNode } from "react";
+import { cn } from "./cn";
 
 /** Props for the {@link FormField} label + control wrapper. */
 export interface FormFieldProps {
@@ -20,20 +21,14 @@ export interface FormFieldProps {
  */
 export function FormField({ label, htmlFor, width, hint, className = "", style = {}, children }: FormFieldProps) {
   return (
-    <div
-      className={`sq-field ${className}`}
-      style={{ display: "flex", flexDirection: "column", gap: "0.35rem", width: width ?? "auto", ...style }}
-    >
+    <div className={cn("sq-field flex flex-col gap-[0.35rem]", className)} style={{ width: width ?? "auto", ...style }}>
       {label != null && (
-        <label
-          htmlFor={htmlFor}
-          style={{ fontSize: "var(--text-xs)", fontWeight: "var(--weight-medium)", color: "var(--text-secondary)" }}
-        >
+        <label htmlFor={htmlFor} className="text-xs font-medium text-fg-secondary">
           {label}
         </label>
       )}
       {children}
-      {hint != null && <span style={{ fontSize: "var(--text-2xs)", color: "var(--text-muted)" }}>{hint}</span>}
+      {hint != null && <span className="text-2xs text-fg-muted">{hint}</span>}
     </div>
   );
 }
diff --git a/packages/dashboard/src/ui/Input.tsx b/packages/dashboard/src/ui/Input.tsx
index 48ba8f9..d39ab3b 100644
--- a/packages/dashboard/src/ui/Input.tsx
+++ b/packages/dashboard/src/ui/Input.tsx
@@ -1,4 +1,5 @@
 import type { InputHTMLAttributes } from "react";
+import { cn } from "./cn";
 
 /** Props for the {@link Input} field. Extends the native `input` attributes. */
 export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size"> {
@@ -12,26 +13,16 @@ export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>,
  * Input — text/number/datetime field, matching the dashboard's filter-bar inputs.
  * Pair with {@link FormField} for a label.
  */
-export function Input({ type = "text", size = "md", invalid = false, className = "", style = {}, ...rest }: InputProps) {
-  const height = size === "sm" ? "var(--control-height-sm)" : "var(--control-height)";
+export function Input({ type = "text", size = "md", invalid = false, className = "", ...rest }: InputProps) {
   return (
     <input
       type={type}
-      className={`sq-input ${className}`}
-      style={{
-        height,
-        width: "100%",
-        padding: "0 0.75rem",
-        fontFamily: "var(--font-sans)",
-        fontSize: "var(--text-sm)",
-        color: "var(--text-primary)",
-        background: "var(--surface-raised)",
-        border: `1px solid ${invalid ? "var(--status-failed)" : "var(--border-strong)"}`,
-        borderRadius: "var(--radius-sm)",
-        transition:
-          "border-color var(--duration-fast) var(--ease-standard), box-shadow var(--duration-fast) var(--ease-standard)",
-        ...style,
-      }}
+      className={cn(
+        "sq-input w-full px-3 font-sans text-sm text-fg bg-surface-raised rounded-sm border transition-[border-color,box-shadow] duration-[120ms] ease-standard placeholder:text-fg-muted focus:outline-none focus:border-brand focus:ring-[3px] focus:ring-brand-ring",
+        size === "sm" ? "h-control-sm" : "h-control",
+        invalid ? "border-status-failed" : "border-edge-strong",
+        className,
+      )}
       {...rest}
     />
   );
diff --git a/packages/dashboard/src/ui/NavItem.tsx b/packages/dashboard/src/ui/NavItem.tsx
index 2bba8dd..0718bed 100644
--- a/packages/dashboard/src/ui/NavItem.tsx
+++ b/packages/dashboard/src/ui/NavItem.tsx
@@ -1,4 +1,5 @@
 import type { CSSProperties, MouseEvent } from "react";
+import { cn } from "./cn";
 import { Icon } from "./Icon";
 
 /** Props for the {@link NavItem} sidebar link. */
@@ -15,30 +16,23 @@ export interface NavItemProps {
 
 /**
  * NavItem — a single sidebar link. The active state gets a subtle raised fill and a
- * brand left-accent; hover lightens (see `.sq-navitem` in the base layer).
+ * brand left-accent; hover lightens.
  */
 export function NavItem({ label, icon, active = false, href = "#", onClick, className = "", style = {} }: NavItemProps) {
   return (
     <a
       href={href}
       onClick={onClick}
-      className={`sq-navitem ${className}`}
-      style={{
-        display: "flex",
-        alignItems: "center",
-        gap: "0.65rem",
-        padding: "0.5rem 0.75rem",
-        borderRadius: "var(--radius-sm)",
-        fontSize: "var(--text-sm)",
-        fontWeight: active ? "var(--weight-semibold)" : "var(--weight-medium)",
-        color: active ? "var(--text-strong)" : "var(--text-primary)",
-        background: active ? "var(--surface-hover)" : "transparent",
-        borderLeft: active ? "2px solid var(--brand-primary)" : "2px solid transparent",
-        textDecoration: "none",
-        ...style,
-      }}
+      className={cn(
+        "sq-navitem flex items-center gap-[0.65rem] px-3 py-2 rounded-sm text-sm no-underline border-l-2 transition-[background-color,color] duration-[120ms] ease-standard hover:bg-surface-hover hover:text-fg-strong",
+        active
+          ? "font-semibold text-fg-strong bg-surface-hover border-brand"
+          : "font-medium text-fg bg-transparent border-transparent",
+        className,
+      )}
+      style={style}
     >
-      {icon && <Icon name={icon} size={16} style={{ color: active ? "var(--brand-primary)" : "var(--text-secondary)" }} />}
+      {icon && <Icon name={icon} size={16} className={active ? "text-brand" : "text-fg-secondary"} />}
       {label}
     </a>
   );
diff --git a/packages/dashboard/src/ui/Pagination.tsx b/packages/dashboard/src/ui/Pagination.tsx
index 35d93f8..3c0a553 100644
--- a/packages/dashboard/src/ui/Pagination.tsx
+++ b/packages/dashboard/src/ui/Pagination.tsx
@@ -1,4 +1,5 @@
 import type { CSSProperties, ReactNode } from "react";
+import { cn } from "./cn";
 
 /** Props for the {@link Pagination} control. */
 export interface PaginationProps {
@@ -20,29 +21,18 @@ export function Pagination({ page, hasNext = false, onPrev, onNext, className =
       type="button"
       disabled={!enabled}
       onClick={enabled ? onClick : undefined}
-      style={{
-        height: "var(--control-height-sm)",
-        minWidth: "2rem",
-        padding: "0 0.7rem",
-        fontSize: "var(--text-xs)",
-        fontWeight: "var(--weight-medium)",
-        fontFamily: "var(--font-sans)",
-        color: active ? "var(--on-brand)" : "var(--text-primary)",
-        background: active ? "var(--brand-primary)" : "var(--surface-raised)",
-        border: "1px solid var(--border-strong)",
-        cursor: enabled ? "pointer" : "not-allowed",
-        opacity: enabled ? 1 : 0.4,
-      }}
+      className={cn(
+        "h-control-sm min-w-8 px-[0.7rem] text-xs font-medium font-sans border border-edge-strong",
+        active ? "text-on-brand bg-brand" : "text-fg bg-surface-raised",
+        enabled ? "cursor-pointer opacity-100 enabled:hover:bg-surface-hover" : "cursor-not-allowed opacity-40",
+      )}
     >
       {content}
     </button>
   );
 
   return (
-    <div
-      className={`sq-pagination ${className}`}
-      style={{ display: "inline-flex", borderRadius: "var(--radius-sm)", overflow: "hidden", ...style }}
-    >
+    <div className={cn("sq-pagination inline-flex rounded-sm overflow-hidden", className)} style={style}>
       {btn("«", page > 1, onPrev, false)}
       {btn(`Page ${page}`, false, undefined, true)}
       {btn("»", hasNext, onNext, false)}
diff --git a/packages/dashboard/src/ui/Select.tsx b/packages/dashboard/src/ui/Select.tsx
index 5f3a541..6ced2fc 100644
--- a/packages/dashboard/src/ui/Select.tsx
+++ b/packages/dashboard/src/ui/Select.tsx
@@ -1,4 +1,6 @@
 import type { SelectHTMLAttributes } from "react";
+import { cn } from "./cn";
+import { Icon } from "./Icon";
 
 /** A single option for {@link Select} when passing data instead of children. */
 export interface SelectOption {
@@ -14,46 +16,35 @@ export interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement
   size?: "sm" | "md";
 }
 
-const CHEVRON =
-  "url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' fill='none' stroke='%239aa6ba' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m6 9 6 6 6-6'/%3E%3C/svg%3E\")";
-
 /**
  * Select — native dropdown styled to match the dashboard's filter selects. Pass
- * `options` as data, or `<option>` children.
+ * `options` as data, or `<option>` children. A non-interactive chevron is overlaid
+ * on the right (the native indicator is removed via `appearance-none`).
  */
-export function Select({ options, size = "md", className = "", style = {}, children, ...rest }: SelectProps) {
-  const height = size === "sm" ? "var(--control-height-sm)" : "var(--control-height)";
+export function Select({ options, size = "md", className = "", children, ...rest }: SelectProps) {
   return (
-    <select
-      className={`sq-select ${className}`}
-      style={{
-        height,
-        width: "100%",
-        padding: "0 2rem 0 0.75rem",
-        fontFamily: "var(--font-sans)",
-        fontSize: "var(--text-sm)",
-        color: "var(--text-primary)",
-        background: "var(--surface-raised)",
-        border: "1px solid var(--border-strong)",
-        borderRadius: "var(--radius-sm)",
-        cursor: "pointer",
-        appearance: "none",
-        backgroundImage: CHEVRON,
-        backgroundRepeat: "no-repeat",
-        backgroundPosition: "right 0.6rem center",
-        transition:
-          "border-color var(--duration-fast) var(--ease-standard), box-shadow var(--duration-fast) var(--ease-standard)",
-        ...style,
-      }}
-      {...rest}
-    >
-      {options
-        ? options.map((o) => (
-            <option key={o.value} value={o.value}>
-              {o.label}
-            </option>
-          ))
-        : children}
-    </select>
+    <div className="relative w-full">
+      <select
+        className={cn(
+          "sq-select w-full appearance-none rounded-sm border border-edge-strong bg-surface-raised pl-3 pr-8 font-sans text-sm text-fg cursor-pointer transition-[border-color,box-shadow] duration-[120ms] ease-standard focus:outline-none focus:border-brand focus:ring-[3px] focus:ring-brand-ring",
+          size === "sm" ? "h-control-sm" : "h-control",
+          className,
+        )}
+        {...rest}
+      >
+        {options
+          ? options.map((o) => (
+              <option key={o.value} value={o.value}>
+                {o.label}
+              </option>
+            ))
+          : children}
+      </select>
+      <Icon
+        name="chevron-down"
+        size={16}
+        className="pointer-events-none absolute right-[0.6rem] top-1/2 -translate-y-1/2 text-fg-secondary"
+      />
+    </div>
   );
 }
diff --git a/packages/dashboard/src/ui/Sidebar.tsx b/packages/dashboard/src/ui/Sidebar.tsx
index dd4c633..907e073 100644
--- a/packages/dashboard/src/ui/Sidebar.tsx
+++ b/packages/dashboard/src/ui/Sidebar.tsx
@@ -1,4 +1,5 @@
 import type { CSSProperties, ReactNode } from "react";
+import { cn } from "./cn";
 
 /** Props for the {@link Sidebar} app rail. */
 export interface SidebarProps {
@@ -28,63 +29,21 @@ export function Sidebar({
 }: SidebarProps) {
   return (
     <aside
-      className={`sq-sidebar ${className}`}
-      style={{
-        width: "var(--sidebar-width)",
-        flexShrink: 0,
-        display: "flex",
-        flexDirection: "column",
-        background: "var(--surface-card)",
-        borderRight: "1px solid var(--border-default)",
-        ...style,
-      }}
+      className={cn("sq-sidebar w-sidebar shrink-0 flex flex-col bg-surface-card border-r border-edge", className)}
+      style={style}
     >
-      <div
-        style={{
-          display: "flex",
-          alignItems: "center",
-          gap: "0.6rem",
-          padding: "var(--space-4)",
-          borderBottom: "1px solid var(--border-subtle)",
-        }}
-      >
+      <div className="flex items-center gap-[0.6rem] p-4 border-b border-edge-subtle">
         {logoSrc ? (
-          <img src={logoSrc} alt="" style={{ height: 40, width: "auto" }} />
+          <img src={logoSrc} alt="" className="h-10 w-auto" />
         ) : (
-          <span
-            aria-hidden
-            style={{ fontFamily: "var(--font-brand)", fontSize: "var(--text-xl)", fontWeight: 600, color: "var(--text-strong)" }}
-          >
+          <span aria-hidden className="font-brand text-xl font-semibold text-fg-strong">
             ◆
           </span>
         )}
-        <span
-          style={{
-            fontFamily: "var(--font-brand)",
-            fontSize: "var(--text-xl)",
-            fontWeight: "var(--weight-semibold)",
-            color: "var(--text-strong)",
-            letterSpacing: "-0.01em",
-          }}
-        >
-          {brand}
-        </span>
+        <span className="font-brand text-xl font-semibold text-fg-strong tracking-[-0.01em]">{brand}</span>
       </div>
-      <nav style={{ flex: 1, padding: "var(--space-4)", display: "flex", flexDirection: "column", gap: "0.25rem" }}>
-        {children}
-      </nav>
-      {footer && (
-        <div
-          style={{
-            padding: "var(--space-4)",
-            borderTop: "1px solid var(--border-subtle)",
-            fontSize: "var(--text-xs)",
-            color: "var(--text-muted)",
-          }}
-        >
-          {footer}
-        </div>
-      )}
+      <nav className="flex-1 p-4 flex flex-col gap-1">{children}</nav>
+      {footer && <div className="p-4 border-t border-edge-subtle text-xs text-fg-muted">{footer}</div>}
     </aside>
   );
 }
diff --git a/packages/dashboard/src/ui/StatCard.tsx b/packages/dashboard/src/ui/StatCard.tsx
index a7fd086..e8b1279 100644
--- a/packages/dashboard/src/ui/StatCard.tsx
+++ b/packages/dashboard/src/ui/StatCard.tsx
@@ -1,4 +1,5 @@
 import type { CSSProperties, ReactNode } from "react";
+import { cn } from "./cn";
 import { Icon } from "./Icon";
 
 /** Number tone for {@link StatCard}. */
@@ -20,12 +21,12 @@ export interface StatCardProps {
   style?: CSSProperties;
 }
 
-const TONES: Record<StatTone, string> = {
-  running: "var(--status-running)",
-  completed: "var(--status-completed)",
-  failed: "var(--status-failed)",
-  scheduled: "var(--status-scheduled)",
-  neutral: "var(--text-strong)",
+const TONE_TEXT: Record<StatTone, string> = {
+  running: "text-status-running",
+  completed: "text-status-completed",
+  failed: "text-status-failed",
+  scheduled: "text-status-scheduled",
+  neutral: "text-fg-strong",
 };
 
 /**
@@ -35,25 +36,16 @@ const TONES: Record<StatTone, string> = {
 export function StatCard({ label, value, tone = "neutral", icon, delta, className = "", style = {} }: StatCardProps) {
   return (
     <div
-      className={`sq-statcard ${className}`}
-      style={{
-        background: "var(--surface-raised)",
-        border: "1px solid var(--border-default)",
-        borderRadius: "var(--radius-md)",
-        padding: "var(--space-4) var(--space-4)",
-        boxShadow: "var(--shadow-sm)",
-        ...style,
-      }}
+      className={cn("sq-statcard bg-surface-raised border border-edge rounded-md p-4 shadow-sm", className)}
+      style={style}
     >
-      <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between" }}>
-        <span style={{ fontSize: "var(--text-sm)", color: "var(--text-secondary)" }}>{label}</span>
-        {icon && <Icon name={icon} size={16} style={{ color: TONES[tone] }} />}
+      <div className="flex items-center justify-between">
+        <span className="text-sm text-fg-secondary">{label}</span>
+        {icon && <Icon name={icon} size={16} className={TONE_TEXT[tone]} />}
       </div>
-      <div style={{ display: "flex", alignItems: "baseline", gap: "0.5rem", marginTop: "0.4rem" }}>
-        <span style={{ fontSize: "var(--text-3xl)", fontWeight: "var(--weight-bold)", color: TONES[tone], lineHeight: 1 }}>
-          {value}
-        </span>
-        {delta && <span style={{ fontSize: "var(--text-xs)", color: "var(--text-muted)" }}>{delta}</span>}
+      <div className="flex items-baseline gap-2 mt-[0.4rem]">
+        <span className={cn("text-3xl font-bold leading-none", TONE_TEXT[tone])}>{value}</span>
+        {delta && <span className="text-xs text-fg-muted">{delta}</span>}
       </div>
     </div>
   );
diff --git a/packages/dashboard/src/ui/StepProgress.tsx b/packages/dashboard/src/ui/StepProgress.tsx
index 833c518..3ad3c9b 100644
--- a/packages/dashboard/src/ui/StepProgress.tsx
+++ b/packages/dashboard/src/ui/StepProgress.tsx
@@ -1,4 +1,5 @@
 import type { CSSProperties } from "react";
+import { cn } from "./cn";
 import { Icon } from "./Icon";
 
 /** Status of a single {@link StepProgress} node. */
@@ -19,12 +20,13 @@ export interface StepProgressProps {
   style?: CSSProperties;
 }
 
-const STEP_TONE: Record<StepStatus, string> = {
-  done: "var(--status-completed)",
-  active: "var(--brand-primary)",
-  failed: "var(--status-failed)",
-  canceled: "var(--text-secondary)",
-  pending: "var(--border-strong)",
+/** Fill utility per status, shared by the node disc and the connecting lines. */
+const TONE_BG: Record<StepStatus, string> = {
+  done: "bg-status-completed",
+  active: "bg-brand",
+  failed: "bg-status-failed",
+  canceled: "bg-fg-secondary",
+  pending: "bg-edge-strong",
 };
 
 const FILLED: StepStatus[] = ["done", "active", "failed", "canceled"];
@@ -35,56 +37,41 @@ const FILLED: StepStatus[] = ["done", "active", "failed", "canceled"];
  */
 export function StepProgress({ steps, className = "", style = {} }: StepProgressProps) {
   return (
-    <div className={`sq-steps ${className}`} style={{ display: "flex", alignItems: "flex-start", width: "100%", ...style }}>
+    <div className={cn("sq-steps flex items-start w-full", className)} style={style}>
       {steps.map((step, i) => {
-        const tone = STEP_TONE[step.status];
         const isLast = i === steps.length - 1;
-        const nextTone = isLast ? null : STEP_TONE[steps[i + 1].status];
-        const lineTone =
-          step.status === "done"
-            ? "var(--status-completed)"
-            : nextTone && nextTone !== STEP_TONE.pending
-              ? tone
-              : "var(--border-default)";
         const filled = FILLED.includes(step.status);
         const leftLine =
           i === 0
-            ? "transparent"
+            ? "bg-transparent"
             : steps[i - 1].status === "done"
-              ? "var(--status-completed)"
+              ? "bg-status-completed"
               : filled
-                ? tone
-                : "var(--border-default)";
+                ? TONE_BG[step.status]
+                : "bg-edge";
+        const rightLine =
+          isLast
+            ? "bg-transparent"
+            : step.status === "done"
+              ? "bg-status-completed"
+              : steps[i + 1].status !== "pending"
+                ? TONE_BG[step.status]
+                : "bg-edge";
         return (
-          <div key={i} style={{ display: "flex", flexDirection: "column", alignItems: "center", flex: 1 }}>
-            <div style={{ display: "flex", alignItems: "center", width: "100%" }}>
-              <div style={{ flex: 1, height: 3, background: leftLine }} />
+          <div key={i} className="flex flex-col items-center flex-1">
+            <div className="flex items-center w-full">
+              <div className={cn("flex-1 h-[3px]", leftLine)} />
               <div
-                style={{
-                  width: 34,
-                  height: 34,
-                  flexShrink: 0,
-                  borderRadius: "var(--radius-full)",
-                  display: "flex",
-                  alignItems: "center",
-                  justifyContent: "center",
-                  background: filled ? tone : "var(--surface-raised)",
-                  border: filled ? "none" : "2px solid var(--border-strong)",
-                  color: filled ? "#fff" : "var(--text-muted)",
-                }}
+                className={cn(
+                  "w-[34px] h-[34px] shrink-0 rounded-full flex items-center justify-center",
+                  filled ? cn(TONE_BG[step.status], "text-white") : "bg-surface-raised border-2 border-edge-strong text-fg-muted",
+                )}
               >
                 <Icon name={step.icon ?? "circle"} size={16} />
               </div>
-              <div style={{ flex: 1, height: 3, background: isLast ? "transparent" : lineTone }} />
+              <div className={cn("flex-1 h-[3px]", rightLine)} />
             </div>
-            <span
-              style={{
-                marginTop: "0.55rem",
-                fontSize: "var(--text-sm)",
-                color: filled ? "var(--text-primary)" : "var(--text-muted)",
-                fontWeight: "var(--weight-medium)",
-              }}
-            >
+            <span className={cn("mt-[0.55rem] text-sm font-medium", filled ? "text-fg" : "text-fg-muted")}>
               {step.label}
             </span>
           </div>
diff --git a/packages/dashboard/src/ui/Table.tsx b/packages/dashboard/src/ui/Table.tsx
index b2743ad..e314a50 100644
--- a/packages/dashboard/src/ui/Table.tsx
+++ b/packages/dashboard/src/ui/Table.tsx
@@ -1,4 +1,5 @@
 import type { CSSProperties, ReactNode } from "react";
+import { cn } from "./cn";
 
 /** A column definition for {@link Table}. */
 export interface Column<Row = Record<string, unknown>> {
@@ -27,6 +28,12 @@ export interface TableProps<Row = Record<string, unknown>> {
   style?: CSSProperties;
 }
 
+const ALIGN: Record<NonNullable<Column["align"]>, string> = {
+  left: "text-left",
+  center: "text-center",
+  right: "text-right",
+};
+
 /**
  * Table — dense dark data table for the jobs and queues lists. Columns describe cells
  * (alignment, monospace, custom render); rows get a hover highlight and optional click.
@@ -41,23 +48,18 @@ export function Table<Row extends Record<string, unknown> = Record<string, unkno
   style = {},
 }: TableProps<Row>) {
   return (
-    <div style={{ overflowX: "auto", ...style }} className={className}>
-      <table style={{ width: "100%", borderCollapse: "collapse", fontSize: "var(--text-sm)" }}>
+    <div className={cn("overflow-x-auto", className)} style={style}>
+      <table className="w-full border-collapse text-sm">
         <thead>
           <tr>
             {columns.map((c) => (
               <th
                 key={c.key}
-                style={{
-                  textAlign: c.align ?? "left",
-                  padding: "0.6rem 0.75rem",
-                  fontSize: "var(--text-xs)",
-                  fontWeight: "var(--weight-semibold)",
-                  color: "var(--text-secondary)",
-                  borderBottom: "1px solid var(--border-default)",
-                  whiteSpace: "nowrap",
-                  width: c.width,
-                }}
+                className={cn(
+                  "px-3 py-[0.6rem] text-xs font-semibold text-fg-secondary border-b border-edge whitespace-nowrap",
+                  ALIGN[c.align ?? "left"],
+                )}
+                style={{ width: c.width }}
               >
                 {c.label}
               </th>
@@ -67,7 +69,7 @@ export function Table<Row extends Record<string, unknown> = Record<string, unkno
         <tbody>
           {rows.length === 0 && (
             <tr>
-              <td colSpan={columns.length} style={{ padding: "2rem", textAlign: "center", color: "var(--text-muted)" }}>
+              <td colSpan={columns.length} className="p-8 text-center text-fg-muted">
                 {empty}
               </td>
             </tr>
@@ -75,21 +77,21 @@ export function Table<Row extends Record<string, unknown> = Record<string, unkno
           {rows.map((row, i) => (
             <tr
               key={(row[rowKey] as string | number | undefined) ?? i}
-              className="sq-row"
+              className={cn(
+                "sq-row transition-colors duration-[120ms] hover:bg-surface-hover",
+                onRowClick ? "cursor-pointer" : "cursor-default",
+              )}
               onClick={onRowClick ? () => onRowClick(row) : undefined}
-              style={{ cursor: onRowClick ? "pointer" : "default" }}
             >
               {columns.map((c) => (
                 <td
                   key={c.key}
-                  style={{
-                    textAlign: c.align ?? "left",
-                    padding: "0.65rem 0.75rem",
-                    color: "var(--text-primary)",
-                    borderBottom: "1px solid var(--border-subtle)",
-                    fontFamily: c.mono ? "var(--font-mono)" : "inherit",
-                    whiteSpace: c.wrap ? "normal" : "nowrap",
-                  }}
+                  className={cn(
+                    "px-3 py-[0.65rem] text-fg border-b border-edge-subtle",
+                    ALIGN[c.align ?? "left"],
+                    c.mono ? "font-mono" : "",
+                    c.wrap ? "whitespace-normal" : "whitespace-nowrap",
+                  )}
                 >
                   {c.render ? c.render(row) : (row[c.key] as ReactNode)}
                 </td>
diff --git a/packages/dashboard/src/ui/ThemeToggle.tsx b/packages/dashboard/src/ui/ThemeToggle.tsx
index 04bc379..767dc00 100644
--- a/packages/dashboard/src/ui/ThemeToggle.tsx
+++ b/packages/dashboard/src/ui/ThemeToggle.tsx
@@ -1,4 +1,5 @@
 import { type ButtonHTMLAttributes, useEffect, useState } from "react";
+import { cn } from "./cn";
 import { Icon } from "./Icon";
 
 /** The two themes the design system ships. */
@@ -16,15 +17,10 @@ export interface ThemeToggleProps extends Omit<ButtonHTMLAttributes<HTMLButtonEl
 
 const STORAGE_KEY = "sq-theme";
 
-interface SizeSpec {
-  box: string;
-  icon: number;
-}
-
-const SIZES: Record<ThemeToggleSize, SizeSpec> = {
-  sm: { box: "var(--control-height-sm)", icon: 15 },
-  md: { box: "var(--control-height)", icon: 17 },
-  lg: { box: "2.75rem", icon: 19 },
+const SIZES: Record<ThemeToggleSize, { box: string; icon: number }> = {
+  sm: { box: "w-control-sm h-control-sm", icon: 15 },
+  md: { box: "w-control h-control", icon: 17 },
+  lg: { box: "w-11 h-11", icon: 19 },
 };
 
 function isTheme(value: string | null): value is Theme {
@@ -64,7 +60,7 @@ function applyTheme(theme: Theme): void {
  * setting `data-theme` on `<html>`, and persists the choice to localStorage. The
  * sun/moon glyph reflects the theme it will switch TO.
  */
-export function ThemeToggle({ size = "md", onChange, className = "", style = {}, ...rest }: ThemeToggleProps) {
+export function ThemeToggle({ size = "md", onChange, className = "", ...rest }: ThemeToggleProps) {
   const [theme, setTheme] = useState<Theme>(readInitial);
   const s = SIZES[size];
 
@@ -88,23 +84,11 @@ export function ThemeToggle({ size = "md", onChange, className = "", style = {},
       aria-label={`Switch to ${isLight ? "dark" : "light"} theme`}
       title={`Switch to ${isLight ? "dark" : "light"} theme`}
       onClick={toggle}
-      className={`sq-btn sq-btn--default ${className}`}
-      style={{
-        display: "inline-flex",
-        alignItems: "center",
-        justifyContent: "center",
-        width: s.box,
-        height: s.box,
-        padding: 0,
-        color: "var(--text-primary)",
-        background: "var(--surface-raised)",
-        border: "1px solid var(--border-strong)",
-        borderRadius: "var(--radius-sm)",
-        cursor: "pointer",
-        transition:
-          "background var(--duration-fast) var(--ease-standard), border-color var(--duration-fast) var(--ease-standard), color var(--duration-fast) var(--ease-standard)",
-        ...style,
-      }}
+      className={cn(
+        "sq-btn sq-btn--default inline-flex items-center justify-center p-0 rounded-sm border border-edge-strong bg-surface-raised text-fg cursor-pointer transition-[background-color,border-color,color] duration-[120ms] ease-standard enabled:hover:bg-surface-hover focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-brand-ring",
+        s.box,
+        className,
+      )}
       {...rest}
     >
       <Icon name={isLight ? "moon" : "sun"} size={s.icon} />
diff --git a/packages/dashboard/src/ui/cn.ts b/packages/dashboard/src/ui/cn.ts
new file mode 100644
index 0000000..64930cc
--- /dev/null
+++ b/packages/dashboard/src/ui/cn.ts
@@ -0,0 +1,10 @@
+import { clsx, type ClassValue } from "clsx";
+
+/**
+ * cn — merges conditional class values into a single className string. Thin wrapper
+ * over {@link clsx}; the components lean on Tailwind utilities, so this is how variant
+ * maps, booleans, and caller-supplied `className` are composed.
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return clsx(inputs);
+}
diff --git a/packages/dashboard/src/ui/styles.css b/packages/dashboard/src/ui/styles.css
index 9352244..67cf46f 100644
--- a/packages/dashboard/src/ui/styles.css
+++ b/packages/dashboard/src/ui/styles.css
@@ -1,7 +1,13 @@
 /* @sidequest/dashboard/ui — global stylesheet.
- * Link this once. It is a manifest of @imports: every design token (fonts, colors,
- * typography, spacing, radii) plus the small base layer with the `.sq-*` interaction
- * classes. Synced from the Sidequest.js design system. Order matters.
+ * Link this once. It wires the design tokens (fonts, colors, typography, spacing,
+ * radii — the source of truth, kept in ./tokens/*.css) into Tailwind CSS v4 via a
+ * `@theme inline` bridge, then pulls in Tailwind itself. The components style
+ * themselves with the resulting utilities (bg-surface-raised, text-fg, rounded-md, …).
+ *
+ * `@theme inline` substitutes the token `var()` straight into the generated utilities
+ * instead of re-declaring the variable, so the semantic color tokens stay theme-aware
+ * (they flip under [data-theme]) and the scale tokens don't collide with themselves.
+ * Order matters: tokens first so their :root vars exist, then Tailwind.
  */
 @import "./tokens/fonts.css";
 @import "./tokens/colors.css";
@@ -9,3 +15,95 @@
 @import "./tokens/spacing.css";
 @import "./tokens/radii.css";
 @import "./tokens/base.css";
+@import "tailwindcss";
+
+/* Scan the component sources for utility usage. */
+@source "./";
+
+@theme inline {
+  /* ---- Surfaces (bg-surface, bg-surface-raised, …) ---- */
+  --color-surface: var(--surface-app);
+  --color-surface-raised: var(--surface-raised);
+  --color-surface-card: var(--surface-card);
+  --color-surface-hover: var(--surface-hover);
+  --color-surface-code: var(--surface-code);
+  --color-surface-inset: var(--surface-inset);
+
+  /* ---- Foreground / text (text-fg, text-fg-muted, …) ---- */
+  --color-fg: var(--text-primary);
+  --color-fg-strong: var(--text-strong);
+  --color-fg-secondary: var(--text-secondary);
+  --color-fg-muted: var(--text-muted);
+  --color-fg-inverse: var(--text-inverse);
+  --color-fg-link: var(--text-link);
+
+  /* ---- Borders (border-edge, border-edge-strong, …) ---- */
+  --color-edge: var(--border-default);
+  --color-edge-strong: var(--border-strong);
+  --color-edge-subtle: var(--border-subtle);
+
+  /* ---- Brand (bg-brand, hover:bg-brand-hover, text-on-brand) ---- */
+  --color-brand: var(--brand-primary);
+  --color-brand-hover: var(--brand-primary-hover);
+  --color-brand-active: var(--brand-primary-active);
+  --color-on-brand: var(--on-brand);
+  --color-brand-ring: var(--brand-ring);
+
+  /* ---- Status (text-status-failed, bg-status-completed, …) ---- */
+  --color-status-running: var(--status-running);
+  --color-status-completed: var(--status-completed);
+  --color-status-failed: var(--status-failed);
+  --color-status-scheduled: var(--status-scheduled);
+
+  /* ---- Fonts (font-sans, font-brand, font-mono) ---- */
+  --font-sans: var(--font-sans);
+  --font-brand: var(--font-brand);
+  --font-mono: var(--font-mono);
+
+  /* ---- Type scale (text-2xs … text-5xl) ---- */
+  --text-2xs: var(--text-2xs);
+  --text-xs: var(--text-xs);
+  --text-sm: var(--text-sm);
+  --text-base: var(--text-base);
+  --text-lg: var(--text-lg);
+  --text-xl: var(--text-xl);
+  --text-2xl: var(--text-2xl);
+  --text-3xl: var(--text-3xl);
+  --text-4xl: var(--text-4xl);
+  --text-5xl: var(--text-5xl);
+
+  /* ---- Line height (leading-tight … leading-relaxed) ---- */
+  --leading-tight: var(--leading-tight);
+  --leading-snug: var(--leading-snug);
+  --leading-normal: var(--leading-normal);
+  --leading-relaxed: var(--leading-relaxed);
+
+  /* ---- Letter spacing (tracking-tight … tracking-caps) ---- */
+  --tracking-tight: var(--tracking-tight);
+  --tracking-normal: var(--tracking-normal);
+  --tracking-wide: var(--tracking-wide);
+  --tracking-caps: var(--tracking-caps);
+
+  /* ---- Radii (rounded-xs … rounded-xl) ---- */
+  --radius-xs: var(--radius-xs);
+  --radius-sm: var(--radius-sm);
+  --radius-md: var(--radius-md);
+  --radius-lg: var(--radius-lg);
+  --radius-xl: var(--radius-xl);
+
+  /* ---- Elevation (shadow-xs … shadow-lg, shadow-glow) ---- */
+  --shadow-xs: var(--shadow-xs);
+  --shadow-sm: var(--shadow-sm);
+  --shadow-md: var(--shadow-md);
+  --shadow-lg: var(--shadow-lg);
+  --shadow-glow: var(--shadow-glow);
+
+  /* ---- Motion (ease-standard, ease-out) ---- */
+  --ease-standard: var(--ease-standard);
+  --ease-out: var(--ease-out);
+
+  /* ---- Layout sizes (w-sidebar, h-control, h-control-sm) ---- */
+  --spacing-sidebar: var(--sidebar-width);
+  --spacing-control: var(--control-height);
+  --spacing-control-sm: var(--control-height-sm);
+}
diff --git a/packages/dashboard/src/ui/tokens/base.css b/packages/dashboard/src/ui/tokens/base.css
index 979e987..66629b6 100644
--- a/packages/dashboard/src/ui/tokens/base.css
+++ b/packages/dashboard/src/ui/tokens/base.css
@@ -45,20 +45,6 @@ body.sq-surface {
 
 ::selection { background: var(--brand-ring); color: #fff; }
 
-/* ---- Component interaction states (inline styles can't express :hover/:focus) ---- */
-.sq-btn:not(:disabled):active { transform: translateY(0.5px); }
-.sq-btn--primary:not(:disabled):hover { background: var(--brand-primary-hover) !important; border-color: var(--brand-primary-hover) !important; }
-.sq-btn--default:not(:disabled):hover { background: var(--surface-hover) !important; }
-.sq-btn--outline:not(:disabled):hover { background: var(--surface-hover) !important; }
-.sq-btn--ghost:not(:disabled):hover { background: var(--surface-hover) !important; }
-.sq-btn--danger:not(:disabled):hover { background: rgba(183, 82, 82, 0.12) !important; border-color: var(--status-failed) !important; }
-.sq-btn:focus-visible { outline: none; box-shadow: var(--focus-ring); }
-
-.sq-input:focus, .sq-select:focus { outline: none; border-color: var(--brand-primary) !important; box-shadow: var(--focus-ring); }
-.sq-input::placeholder { color: var(--text-muted); }
-
-.sq-row { transition: background var(--duration-fast) var(--ease-standard); }
-.sq-row:hover { background: var(--surface-hover); }
-
-.sq-navitem { transition: background var(--duration-fast) var(--ease-standard), color var(--duration-fast) var(--ease-standard); }
-.sq-navitem:hover { background: var(--surface-hover); color: var(--text-strong); }
+/* Interaction states (:hover / :focus-visible / :active) and layout now live on the
+ * components as Tailwind utility variants. The `.sq-*` class names remain on the
+ * elements as stable styling hooks, but carry no CSS here. */
diff --git a/packages/dashboard/vite.lib.config.ts b/packages/dashboard/vite.lib.config.ts
index 3376f9e..03e1521 100644
--- a/packages/dashboard/vite.lib.config.ts
+++ b/packages/dashboard/vite.lib.config.ts
@@ -1,25 +1,15 @@
 import react from "@vitejs/plugin-react";
-import { cpSync } from "node:fs";
 import { resolve } from "node:path";
 import { defineConfig } from "vite";
 import dts from "vite-plugin-dts";
 
 const pkgDir = import.meta.dirname;
 
-// The design tokens ship as plain CSS (consumers link `@sidequest/dashboard/ui/styles.css`).
-// The lib entry stays JS-only, so copy the token stylesheet tree into dist after the build.
-function copyTokenCss() {
-  return {
-    name: "sq-copy-ui-css",
-    closeBundle() {
-      cpSync(resolve(pkgDir, "src/ui/styles.css"), resolve(pkgDir, "dist/ui/styles.css"));
-      cpSync(resolve(pkgDir, "src/ui/tokens"), resolve(pkgDir, "dist/ui/tokens"), { recursive: true });
-    },
-  };
-}
-
-// Vite builds the `@sidequest/dashboard/ui` component library. The Express
-// server keeps its own Rollup build (see rollup.config.js) untouched.
+// Vite builds the `@sidequest/dashboard/ui` component library (JS only). The shipped
+// stylesheet (`@sidequest/dashboard/ui/styles.css`) is compiled separately by the
+// Tailwind CLI in the build script — it inlines the design tokens and the utilities
+// the components use into a single self-contained file. The Express server keeps its
+// own Rollup build (see rollup.config.js) untouched.
 export default defineConfig({
   plugins: [
     react(),
@@ -30,7 +20,6 @@ export default defineConfig({
       exclude: ["src/ui/**/*.test.tsx", "src/ui/**/*.stories.tsx"],
       outDir: resolve(pkgDir, "dist/ui"),
     }),
-    copyTokenCss(),
   ],
   build: {
     outDir: resolve(pkgDir, "dist/ui"),
diff --git a/yarn.lock b/yarn.lock
index 730144f..bb056b2 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -4001,6 +4001,7 @@ __metadata:
     "@types/react-dom": "npm:^19.2.3"
     "@vitejs/plugin-react": "npm:^6.0.3"
     chart.js: "npm:^4.5.1"
+    clsx: "npm:^2.1.1"
     daisyui: "npm:5.1.7"
     ejs: "npm:^4.0.1"
     express: "npm:^5.2.1"
@@ -4021,6 +4022,8 @@ __metadata:
     react: "*"
     react-dom: "*"
   peerDependenciesMeta:
+    lucide-react:
+      optional: true
     react:
       optional: true
     react-dom:
@@ -6594,6 +6597,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"clsx@npm:^2.1.1":
+  version: 2.1.1
+  resolution: "clsx@npm:2.1.1"
+  checksum: 10c0/c4c8eb865f8c82baab07e71bfa8897c73454881c4f99d6bc81585aecd7c441746c1399d08363dc096c550cceaf97bd4ce1e8854e1771e9998d9f94c4fe075839
+  languageName: node
+  linkType: hard
+
 "cmd-shim@npm:^8.0.0":
   version: 8.0.0
   resolution: "cmd-shim@npm:8.0.0"

From 8b08ec33a51417ca8929f09039f43a4134c21bb2 Mon Sep 17 00:00:00 2001
From: merencia <lucas.merencia@gmail.com>
Date: Wed, 8 Jul 2026 16:19:11 -0300
Subject: [PATCH 7/7] refactor(dashboard): type Icon names as keyof typeof
 icons (PascalCase)

Type the Icon `name` prop (and the icon props that feed it: Button, NavItem,
StatCard, StepProgress) as `IconName = keyof typeof icons`, so a wrong icon
name is a compile error instead of a silent no-op. Names are now the Lucide
PascalCase keys (the package's own export names), dropping the kebab->Pascal
conversion. The unknown-name guard stays for runtime safety.

Addresses review on Icon.tsx (Giovani: "keyof typeof icons?").
---
 packages/dashboard/src/ui/Button.stories.tsx  |  4 ++--
 packages/dashboard/src/ui/Button.test.tsx     |  4 ++--
 packages/dashboard/src/ui/Button.tsx          |  6 ++---
 packages/dashboard/src/ui/Icon.stories.tsx    |  8 +++----
 packages/dashboard/src/ui/Icon.test.tsx       |  8 +++----
 packages/dashboard/src/ui/Icon.tsx            | 18 +++++---------
 packages/dashboard/src/ui/NavItem.stories.tsx | 10 ++++----
 packages/dashboard/src/ui/NavItem.test.tsx    |  4 ++--
 packages/dashboard/src/ui/NavItem.tsx         |  4 ++--
 packages/dashboard/src/ui/Select.tsx          |  2 +-
 packages/dashboard/src/ui/Sidebar.stories.tsx |  6 ++---
 .../dashboard/src/ui/StatCard.stories.tsx     | 10 ++++----
 packages/dashboard/src/ui/StatCard.test.tsx   |  2 +-
 packages/dashboard/src/ui/StatCard.tsx        |  4 ++--
 .../dashboard/src/ui/StepProgress.stories.tsx | 24 +++++++++----------
 .../dashboard/src/ui/StepProgress.test.tsx    |  8 +++----
 packages/dashboard/src/ui/StepProgress.tsx    |  6 ++---
 packages/dashboard/src/ui/ThemeToggle.tsx     |  2 +-
 18 files changed, 62 insertions(+), 68 deletions(-)

diff --git a/packages/dashboard/src/ui/Button.stories.tsx b/packages/dashboard/src/ui/Button.stories.tsx
index 72dc328..81f3fce 100644
--- a/packages/dashboard/src/ui/Button.stories.tsx
+++ b/packages/dashboard/src/ui/Button.stories.tsx
@@ -12,9 +12,9 @@ type Story = StoryObj<typeof meta>;
 
 export const Primary: Story = { args: { variant: "primary", children: "Enqueue job" } };
 
-export const WithIcon: Story = { args: { variant: "default", icon: "play", children: "Run" } };
+export const WithIcon: Story = { args: { variant: "default", icon: "Play", children: "Run" } };
 
-export const Danger: Story = { args: { variant: "danger", icon: "trash-2", children: "Delete" } };
+export const Danger: Story = { args: { variant: "danger", icon: "Trash2", children: "Delete" } };
 
 export const Variants: Story = {
   render: () => (
diff --git a/packages/dashboard/src/ui/Button.test.tsx b/packages/dashboard/src/ui/Button.test.tsx
index eb5ed92..919a7b5 100644
--- a/packages/dashboard/src/ui/Button.test.tsx
+++ b/packages/dashboard/src/ui/Button.test.tsx
@@ -19,8 +19,8 @@ describe("Button", () => {
         variant="primary"
         size="lg"
         type="submit"
-        icon="play"
-        iconRight="x"
+        icon="Play"
+        iconRight="X"
         disabled
         block
         active
diff --git a/packages/dashboard/src/ui/Button.tsx b/packages/dashboard/src/ui/Button.tsx
index 483514c..f6ff022 100644
--- a/packages/dashboard/src/ui/Button.tsx
+++ b/packages/dashboard/src/ui/Button.tsx
@@ -1,6 +1,6 @@
 import type { ButtonHTMLAttributes } from "react";
 import { cn } from "./cn";
-import { Icon } from "./Icon";
+import { Icon, type IconName } from "./Icon";
 
 /** Visual treatments for {@link Button}. */
 export type ButtonVariant = "primary" | "default" | "outline" | "ghost" | "danger";
@@ -14,9 +14,9 @@ export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   /** @default "md" */
   size?: ButtonSize;
   /** Leading Lucide icon name. */
-  icon?: string;
+  icon?: IconName;
   /** Trailing Lucide icon name. */
-  iconRight?: string;
+  iconRight?: IconName;
   /** Full-width. */
   block?: boolean;
   /** Pressed/selected look (e.g. active pagination). */
diff --git a/packages/dashboard/src/ui/Icon.stories.tsx b/packages/dashboard/src/ui/Icon.stories.tsx
index c3e90bf..c35eae8 100644
--- a/packages/dashboard/src/ui/Icon.stories.tsx
+++ b/packages/dashboard/src/ui/Icon.stories.tsx
@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import { Icon } from "./Icon";
+import { Icon, type IconName } from "./Icon";
 
 const meta = {
   title: "Actions/Icon",
@@ -10,11 +10,11 @@ export default meta;
 
 type Story = StoryObj<typeof meta>;
 
-export const Play: Story = { args: { name: "play" } };
+export const Play: Story = { args: { name: "Play" } };
 
-export const Large: Story = { args: { name: "refresh-ccw", size: 32 } };
+export const Large: Story = { args: { name: "RefreshCcw", size: 32 } };
 
-const NAMES = ["play", "x", "refresh-ccw", "trash-2", "clock", "activity", "circle-check", "circle-x", "pause"];
+const NAMES: IconName[] = ["Play", "X", "RefreshCcw", "Trash2", "Clock", "Activity", "CircleCheck", "CircleX", "Pause"];
 
 export const Gallery: Story = {
   render: () => (
diff --git a/packages/dashboard/src/ui/Icon.test.tsx b/packages/dashboard/src/ui/Icon.test.tsx
index 6d725ee..cfb774f 100644
--- a/packages/dashboard/src/ui/Icon.test.tsx
+++ b/packages/dashboard/src/ui/Icon.test.tsx
@@ -1,10 +1,10 @@
 import { render } from "@testing-library/react";
 import { describe, expect, it } from "vitest";
-import { Icon } from "./Icon";
+import { Icon, type IconName } from "./Icon";
 
 describe("Icon", () => {
   it("renders a lucide glyph for a known name with defaults", () => {
-    const { container } = render(<Icon name="play" />);
+    const { container } = render(<Icon name="Play" />);
 
     const svg = container.querySelector("svg");
     expect(svg).not.toBeNull();
@@ -13,7 +13,7 @@ describe("Icon", () => {
   });
 
   it("resolves multi-segment names and honors size/strokeWidth/rest props", () => {
-    const { container } = render(<Icon name="refresh-ccw" size={24} strokeWidth={3} className="x" />);
+    const { container } = render(<Icon name="RefreshCcw" size={24} strokeWidth={3} className="x" />);
 
     const svg = container.querySelector("svg");
     expect(svg).toHaveAttribute("width", "24");
@@ -22,7 +22,7 @@ describe("Icon", () => {
   });
 
   it("renders nothing for an unknown name", () => {
-    const { container } = render(<Icon name="definitely-not-an-icon" />);
+    const { container } = render(<Icon name={"definitely-not-an-icon" as IconName} />);
 
     expect(container.querySelector("svg")).toBeNull();
   });
diff --git a/packages/dashboard/src/ui/Icon.tsx b/packages/dashboard/src/ui/Icon.tsx
index bb77a39..382c652 100644
--- a/packages/dashboard/src/ui/Icon.tsx
+++ b/packages/dashboard/src/ui/Icon.tsx
@@ -1,32 +1,26 @@
 import { icons, type LucideProps } from "lucide-react";
 import type { ComponentType } from "react";
 
+/** A Lucide icon key, e.g. "Play", "RefreshCcw", "X". */
+export type IconName = keyof typeof icons;
+
 /** Props for the {@link Icon} component. Extends the underlying Lucide SVG props. */
 export interface IconProps extends Omit<LucideProps, "ref"> {
-  /** Lucide icon name, kebab or space separated, e.g. "play", "x", "refresh-ccw". */
-  name: string;
+  /** Lucide icon key (PascalCase, as exported by lucide-react), e.g. "Play", "RefreshCcw", "X". */
+  name: IconName;
   /** Pixel size. @default 16 */
   size?: number;
   /** @default 2 */
   strokeWidth?: number;
 }
 
-/** "refresh-ccw" | "refresh ccw" -> "RefreshCcw" (the Lucide component key). */
-function toPascalCase(name: string): string {
-  return name
-    .split(/[-_ ]+/)
-    .filter(Boolean)
-    .map((part) => part[0].toUpperCase() + part.slice(1))
-    .join("");
-}
-
 /**
  * Icon — a Lucide glyph resolved by name (Feather's successor; the design system's
  * iconography). Renders `currentColor`, so it inherits the surrounding text color.
  * Returns nothing for an unknown name.
  */
 export function Icon({ name, size = 16, strokeWidth = 2, ...rest }: IconProps) {
-  const Glyph = icons[toPascalCase(name) as keyof typeof icons] as ComponentType<LucideProps> | undefined;
+  const Glyph = icons[name] as ComponentType<LucideProps> | undefined;
   if (!Glyph) {
     return null;
   }
diff --git a/packages/dashboard/src/ui/NavItem.stories.tsx b/packages/dashboard/src/ui/NavItem.stories.tsx
index 778db43..1122dfa 100644
--- a/packages/dashboard/src/ui/NavItem.stories.tsx
+++ b/packages/dashboard/src/ui/NavItem.stories.tsx
@@ -11,16 +11,16 @@ export default meta;
 
 type Story = StoryObj<typeof meta>;
 
-export const Active: Story = { args: { label: "Dashboard", icon: "layout-dashboard", active: true } };
+export const Active: Story = { args: { label: "Dashboard", icon: "LayoutDashboard", active: true } };
 
-export const Inactive: Story = { args: { label: "Jobs", icon: "list" } };
+export const Inactive: Story = { args: { label: "Jobs", icon: "List" } };
 
 export const List: Story = {
   render: () => (
     <div style={{ width: "14rem", display: "flex", flexDirection: "column", gap: "0.25rem" }}>
-      <NavItem label="Dashboard" icon="layout-dashboard" active />
-      <NavItem label="Jobs" icon="list" />
-      <NavItem label="Queues" icon="layers" />
+      <NavItem label="Dashboard" icon="LayoutDashboard" active />
+      <NavItem label="Jobs" icon="List" />
+      <NavItem label="Queues" icon="Layers" />
     </div>
   ),
 };
diff --git a/packages/dashboard/src/ui/NavItem.test.tsx b/packages/dashboard/src/ui/NavItem.test.tsx
index 11ac998..c244405 100644
--- a/packages/dashboard/src/ui/NavItem.test.tsx
+++ b/packages/dashboard/src/ui/NavItem.test.tsx
@@ -13,7 +13,7 @@ describe("NavItem", () => {
   });
 
   it("renders an inactive link with an icon (muted icon color)", () => {
-    const { container } = render(<NavItem label="Jobs" icon="list" />);
+    const { container } = render(<NavItem label="Jobs" icon="List" />);
 
     expect(screen.getByRole("link", { name: /Jobs/ })).toBeInTheDocument();
     expect(container.querySelector("svg")).not.toBeNull();
@@ -21,7 +21,7 @@ describe("NavItem", () => {
 
   it("renders an active link with an icon, href, className and style", () => {
     const { container } = render(
-      <NavItem label="Queues" icon="layers" active href="/queues" className="extra" style={{ opacity: 1 }} />,
+      <NavItem label="Queues" icon="Layers" active href="/queues" className="extra" style={{ opacity: 1 }} />,
     );
 
     const link = screen.getByRole("link", { name: /Queues/ });
diff --git a/packages/dashboard/src/ui/NavItem.tsx b/packages/dashboard/src/ui/NavItem.tsx
index 0718bed..ff0e415 100644
--- a/packages/dashboard/src/ui/NavItem.tsx
+++ b/packages/dashboard/src/ui/NavItem.tsx
@@ -1,12 +1,12 @@
 import type { CSSProperties, MouseEvent } from "react";
 import { cn } from "./cn";
-import { Icon } from "./Icon";
+import { Icon, type IconName } from "./Icon";
 
 /** Props for the {@link NavItem} sidebar link. */
 export interface NavItemProps {
   label: string;
   /** Lucide icon name. */
-  icon?: string;
+  icon?: IconName;
   active?: boolean;
   href?: string;
   onClick?: (e: MouseEvent) => void;
diff --git a/packages/dashboard/src/ui/Select.tsx b/packages/dashboard/src/ui/Select.tsx
index 6ced2fc..198df41 100644
--- a/packages/dashboard/src/ui/Select.tsx
+++ b/packages/dashboard/src/ui/Select.tsx
@@ -41,7 +41,7 @@ export function Select({ options, size = "md", className = "", children, ...rest
           : children}
       </select>
       <Icon
-        name="chevron-down"
+        name="ChevronDown"
         size={16}
         className="pointer-events-none absolute right-[0.6rem] top-1/2 -translate-y-1/2 text-fg-secondary"
       />
diff --git a/packages/dashboard/src/ui/Sidebar.stories.tsx b/packages/dashboard/src/ui/Sidebar.stories.tsx
index deec42b..a70c7bb 100644
--- a/packages/dashboard/src/ui/Sidebar.stories.tsx
+++ b/packages/dashboard/src/ui/Sidebar.stories.tsx
@@ -15,9 +15,9 @@ export const Default: Story = {
   render: () => (
     <div style={{ height: "26rem", display: "flex" }}>
       <Sidebar>
-        <NavItem label="Dashboard" icon="layout-dashboard" active />
-        <NavItem label="Jobs" icon="list" />
-        <NavItem label="Queues" icon="layers" />
+        <NavItem label="Dashboard" icon="LayoutDashboard" active />
+        <NavItem label="Jobs" icon="List" />
+        <NavItem label="Queues" icon="Layers" />
       </Sidebar>
     </div>
   ),
diff --git a/packages/dashboard/src/ui/StatCard.stories.tsx b/packages/dashboard/src/ui/StatCard.stories.tsx
index 6ac2386..a532458 100644
--- a/packages/dashboard/src/ui/StatCard.stories.tsx
+++ b/packages/dashboard/src/ui/StatCard.stories.tsx
@@ -12,16 +12,16 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Completed: Story = {
-  args: { label: "Completed", value: "1,284", tone: "completed", icon: "circle-check" },
+  args: { label: "Completed", value: "1,284", tone: "completed", icon: "CircleCheck" },
 };
 
 export const Row: Story = {
   render: () => (
     <div style={{ display: "grid", gridTemplateColumns: "repeat(4, 1fr)", gap: "1rem" }}>
-      <StatCard label="Running" value={12} tone="running" icon="activity" />
-      <StatCard label="Completed" value="1,284" tone="completed" icon="circle-check" />
-      <StatCard label="Failed" value={7} tone="failed" icon="circle-x" delta="+2" />
-      <StatCard label="Scheduled" value={40} tone="scheduled" icon="clock" />
+      <StatCard label="Running" value={12} tone="running" icon="Activity" />
+      <StatCard label="Completed" value="1,284" tone="completed" icon="CircleCheck" />
+      <StatCard label="Failed" value={7} tone="failed" icon="CircleX" delta="+2" />
+      <StatCard label="Scheduled" value={40} tone="scheduled" icon="Clock" />
     </div>
   ),
 };
diff --git a/packages/dashboard/src/ui/StatCard.test.tsx b/packages/dashboard/src/ui/StatCard.test.tsx
index f696fd7..75946a5 100644
--- a/packages/dashboard/src/ui/StatCard.test.tsx
+++ b/packages/dashboard/src/ui/StatCard.test.tsx
@@ -13,7 +13,7 @@ describe("StatCard", () => {
 
   it("renders a tone, icon, delta and className", () => {
     const { container } = render(
-      <StatCard label="Failed" value={3} tone="failed" icon="activity" delta="+2 today" className="extra" style={{}} />,
+      <StatCard label="Failed" value={3} tone="failed" icon="Activity" delta="+2 today" className="extra" style={{}} />,
     );
 
     expect(container.querySelector(".sq-statcard")).toHaveClass("extra");
diff --git a/packages/dashboard/src/ui/StatCard.tsx b/packages/dashboard/src/ui/StatCard.tsx
index e8b1279..411d8f0 100644
--- a/packages/dashboard/src/ui/StatCard.tsx
+++ b/packages/dashboard/src/ui/StatCard.tsx
@@ -1,6 +1,6 @@
 import type { CSSProperties, ReactNode } from "react";
 import { cn } from "./cn";
-import { Icon } from "./Icon";
+import { Icon, type IconName } from "./Icon";
 
 /** Number tone for {@link StatCard}. */
 export type StatTone = "running" | "completed" | "failed" | "scheduled" | "neutral";
@@ -14,7 +14,7 @@ export interface StatCardProps {
   /** Number color. @default "neutral" */
   tone?: StatTone;
   /** Lucide icon in the top-right. */
-  icon?: string;
+  icon?: IconName;
   /** Small delta/subtext next to the value. */
   delta?: string;
   className?: string;
diff --git a/packages/dashboard/src/ui/StepProgress.stories.tsx b/packages/dashboard/src/ui/StepProgress.stories.tsx
index 7a14bde..5cae38e 100644
--- a/packages/dashboard/src/ui/StepProgress.stories.tsx
+++ b/packages/dashboard/src/ui/StepProgress.stories.tsx
@@ -14,10 +14,10 @@ type Story = StoryObj<typeof meta>;
 export const Completed: Story = {
   args: {
     steps: [
-      { label: "Enqueued", icon: "inbox", status: "done" },
-      { label: "Claimed", icon: "user-check", status: "done" },
-      { label: "Running", icon: "activity", status: "done" },
-      { label: "Completed", icon: "circle-check", status: "done" },
+      { label: "Enqueued", icon: "Inbox", status: "done" },
+      { label: "Claimed", icon: "UserCheck", status: "done" },
+      { label: "Running", icon: "Activity", status: "done" },
+      { label: "Completed", icon: "CircleCheck", status: "done" },
     ],
   },
 };
@@ -25,10 +25,10 @@ export const Completed: Story = {
 export const Running: Story = {
   args: {
     steps: [
-      { label: "Enqueued", icon: "inbox", status: "done" },
-      { label: "Claimed", icon: "user-check", status: "done" },
-      { label: "Running", icon: "activity", status: "active" },
-      { label: "Completed", icon: "circle-check", status: "pending" },
+      { label: "Enqueued", icon: "Inbox", status: "done" },
+      { label: "Claimed", icon: "UserCheck", status: "done" },
+      { label: "Running", icon: "Activity", status: "active" },
+      { label: "Completed", icon: "CircleCheck", status: "pending" },
     ],
   },
 };
@@ -36,10 +36,10 @@ export const Running: Story = {
 export const Failed: Story = {
   args: {
     steps: [
-      { label: "Enqueued", icon: "inbox", status: "done" },
-      { label: "Claimed", icon: "user-check", status: "done" },
-      { label: "Running", icon: "activity", status: "failed" },
-      { label: "Completed", icon: "circle-check", status: "canceled" },
+      { label: "Enqueued", icon: "Inbox", status: "done" },
+      { label: "Claimed", icon: "UserCheck", status: "done" },
+      { label: "Running", icon: "Activity", status: "failed" },
+      { label: "Completed", icon: "CircleCheck", status: "canceled" },
     ],
   },
 };
diff --git a/packages/dashboard/src/ui/StepProgress.test.tsx b/packages/dashboard/src/ui/StepProgress.test.tsx
index ba1f112..dd1b251 100644
--- a/packages/dashboard/src/ui/StepProgress.test.tsx
+++ b/packages/dashboard/src/ui/StepProgress.test.tsx
@@ -5,10 +5,10 @@ import { StepProgress, type Step } from "./StepProgress";
 describe("StepProgress", () => {
   it("renders a mixed-status timeline covering every node treatment", () => {
     const steps: Step[] = [
-      { label: "Enqueued", icon: "inbox", status: "done" },
-      { label: "Claimed", status: "active" }, // no icon -> "circle"
-      { label: "Running", icon: "play", status: "pending" },
-      { label: "Failed", icon: "x", status: "failed" },
+      { label: "Enqueued", icon: "Inbox", status: "done" },
+      { label: "Claimed", status: "active" }, // no icon -> "Circle"
+      { label: "Running", icon: "Play", status: "pending" },
+      { label: "Failed", icon: "X", status: "failed" },
     ];
     render(<StepProgress steps={steps} />);
 
diff --git a/packages/dashboard/src/ui/StepProgress.tsx b/packages/dashboard/src/ui/StepProgress.tsx
index 3ad3c9b..8022768 100644
--- a/packages/dashboard/src/ui/StepProgress.tsx
+++ b/packages/dashboard/src/ui/StepProgress.tsx
@@ -1,6 +1,6 @@
 import type { CSSProperties } from "react";
 import { cn } from "./cn";
-import { Icon } from "./Icon";
+import { Icon, type IconName } from "./Icon";
 
 /** Status of a single {@link StepProgress} node. */
 export type StepStatus = "done" | "active" | "failed" | "canceled" | "pending";
@@ -9,7 +9,7 @@ export type StepStatus = "done" | "active" | "failed" | "canceled" | "pending";
 export interface Step {
   label: string;
   /** Lucide icon name for the node. */
-  icon?: string;
+  icon?: IconName;
   status: StepStatus;
 }
 
@@ -67,7 +67,7 @@ export function StepProgress({ steps, className = "", style = {} }: StepProgress
                   filled ? cn(TONE_BG[step.status], "text-white") : "bg-surface-raised border-2 border-edge-strong text-fg-muted",
                 )}
               >
-                <Icon name={step.icon ?? "circle"} size={16} />
+                <Icon name={step.icon ?? "Circle"} size={16} />
               </div>
               <div className={cn("flex-1 h-[3px]", rightLine)} />
             </div>
diff --git a/packages/dashboard/src/ui/ThemeToggle.tsx b/packages/dashboard/src/ui/ThemeToggle.tsx
index 767dc00..b3f1711 100644
--- a/packages/dashboard/src/ui/ThemeToggle.tsx
+++ b/packages/dashboard/src/ui/ThemeToggle.tsx
@@ -91,7 +91,7 @@ export function ThemeToggle({ size = "md", onChange, className = "", ...rest }:
       )}
       {...rest}
     >
-      <Icon name={isLight ? "moon" : "sun"} size={s.icon} />
+      <Icon name={isLight ? "Moon" : "Sun"} size={s.icon} />
     </button>
   );
 }