From 6344a513ce8066e61ff0eae90280e1e386a63915 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ullrich=20Sch=C3=A4fer?= <hi+github@ullrich.is>
Date: Wed, 15 Jul 2026 23:32:28 +0200
Subject: [PATCH] feat(ui): shared primitives (Button, Badge, Card, Input) on
 the tokens
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Second step of the visual-redesign (tokens -> primitives -> surfaces):
a small set of shared, token-driven primitives in @trails-cool/ui so
both apps compose from one styled vocabulary instead of hand-rolling
bg-white/text-gray-* per screen.

- @trails-cool/ui now ships React components (Button variants+sizes,
  Badge tones, Card raised/subtle, Input) plus a tiny cn() helper.
  React is a peer dep; package builds with no bundling step.
- Co-located jsdom unit tests (@testing-library/react) assert roles,
  token classes, variant switching, and behavior — run in the existing
  Unit Tests gate, cross-platform, no snapshot baseline needed.
- Tailwind @source directive in both apps' styles.css so the package's
  token utility classes get generated.
- Dev-only /dev/ui gallery route in the planner renders every primitive
  in all states — a zero-dependency stand-in for Storybook. Excluded
  from production builds (NODE_ENV guard in routes.ts).

No app surfaces are refactored yet; adopting the primitives in the
topbar/sidebar/etc. is the surface task groups.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/journal/app/styles.css        |  3 ++
 apps/planner/app/routes.ts         |  5 ++
 apps/planner/app/routes/dev.ui.tsx | 73 ++++++++++++++++++++++++++++++
 apps/planner/app/styles.css        |  3 ++
 packages/ui/package.json           | 18 ++++++++
 packages/ui/src/Badge.test.tsx     | 22 +++++++++
 packages/ui/src/Badge.tsx          | 21 +++++++++
 packages/ui/src/Button.test.tsx    | 55 ++++++++++++++++++++++
 packages/ui/src/Button.tsx         | 44 ++++++++++++++++++
 packages/ui/src/Card.test.tsx      | 22 +++++++++
 packages/ui/src/Card.tsx           | 20 ++++++++
 packages/ui/src/Input.test.tsx     | 26 +++++++++++
 packages/ui/src/Input.tsx          | 15 ++++++
 packages/ui/src/cn.ts              |  4 ++
 packages/ui/src/index.ts           |  9 ++++
 packages/ui/tsconfig.json          | 10 ++++
 packages/ui/vitest.config.ts       |  1 +
 pnpm-lock.yaml                     | 13 ++++++
 18 files changed, 364 insertions(+)
 create mode 100644 apps/planner/app/routes/dev.ui.tsx
 create mode 100644 packages/ui/src/Badge.test.tsx
 create mode 100644 packages/ui/src/Badge.tsx
 create mode 100644 packages/ui/src/Button.test.tsx
 create mode 100644 packages/ui/src/Button.tsx
 create mode 100644 packages/ui/src/Card.test.tsx
 create mode 100644 packages/ui/src/Card.tsx
 create mode 100644 packages/ui/src/Input.test.tsx
 create mode 100644 packages/ui/src/Input.tsx
 create mode 100644 packages/ui/src/cn.ts
 create mode 100644 packages/ui/src/index.ts
 create mode 100644 packages/ui/tsconfig.json
 create mode 100644 packages/ui/vitest.config.ts

diff --git a/apps/journal/app/styles.css b/apps/journal/app/styles.css
index 8eff5ef..a6335a7 100644
--- a/apps/journal/app/styles.css
+++ b/apps/journal/app/styles.css
@@ -1,6 +1,9 @@
 @import "tailwindcss";
 @import "@trails-cool/ui/theme.css";
 
+/* Scan the shared UI package so its token utility classes are generated. */
+@source "../../../packages/ui/src";
+
 @keyframes slide {
   0% { transform: translateX(-100%); }
   100% { transform: translateX(400%); }
diff --git a/apps/planner/app/routes.ts b/apps/planner/app/routes.ts
index 53f07f0..aac17d0 100644
--- a/apps/planner/app/routes.ts
+++ b/apps/planner/app/routes.ts
@@ -9,4 +9,9 @@ export default [
   route("api/pois", "routes/api.pois.ts"),
   route("api/save-to-journal", "routes/api.save-to-journal.ts"),
   route("session/:id", "routes/session.$id.tsx"),
+  // Dev-only component gallery for the shared @trails-cool/ui primitives —
+  // our lightweight stand-in for Storybook. Not compiled in production builds.
+  ...(process.env.NODE_ENV === "production"
+    ? []
+    : [route("dev/ui", "routes/dev.ui.tsx")]),
 ] satisfies RouteConfig;
diff --git a/apps/planner/app/routes/dev.ui.tsx b/apps/planner/app/routes/dev.ui.tsx
new file mode 100644
index 0000000..9933fd4
--- /dev/null
+++ b/apps/planner/app/routes/dev.ui.tsx
@@ -0,0 +1,73 @@
+import type { ReactNode } from "react";
+import { Badge, Button, Card, Input } from "@trails-cool/ui";
+
+/**
+ * Dev-only gallery for the shared UI primitives. Renders every primitive in
+ * its variants/states on one page so components can be built and eyeballed in
+ * isolation — the lightweight alternative to Storybook. Registered only in
+ * non-production builds (see routes.ts).
+ */
+function Section({ title, children }: { title: string; children: ReactNode }) {
+  return (
+    <section className="space-y-3">
+      <h2 className="font-mono text-xs uppercase tracking-wider text-text-lo">
+        {title}
+      </h2>
+      <div className="flex flex-wrap items-center gap-3">{children}</div>
+    </section>
+  );
+}
+
+export default function DevUi() {
+  return (
+    <main className="mx-auto max-w-3xl space-y-10 p-10">
+      <header className="space-y-1">
+        <h1 className="text-2xl font-semibold text-text-hi">UI primitives</h1>
+        <p className="text-sm text-text-md">
+          Shared <code className="font-mono">@trails-cool/ui</code> components on
+          the design-system tokens.
+        </p>
+      </header>
+
+      <Section title="Button · variants">
+        <Button variant="primary">Primary</Button>
+        <Button variant="secondary">Secondary</Button>
+        <Button variant="ghost">Ghost</Button>
+        <Button variant="primary" disabled>
+          Disabled
+        </Button>
+      </Section>
+
+      <Section title="Button · sizes">
+        <Button size="sm">Small</Button>
+        <Button size="md">Medium</Button>
+      </Section>
+
+      <Section title="Badge · tones">
+        <Badge>Neutral</Badge>
+        <Badge tone="accent">Elevation</Badge>
+        <Badge tone="stop">NIGHT 2</Badge>
+      </Section>
+
+      <Section title="Input">
+        <div className="w-72">
+          <Input placeholder="Route name…" />
+        </div>
+        <div className="w-72">
+          <Input value="Alpenüberquerung" readOnly />
+        </div>
+      </Section>
+
+      <Section title="Card">
+        <Card className="w-64">
+          <h3 className="font-medium text-text-hi">Subtle card</h3>
+          <p className="mt-1 text-sm text-text-md">On a subtle surface tone.</p>
+        </Card>
+        <Card raised className="w-64">
+          <h3 className="font-medium text-text-hi">Raised card</h3>
+          <p className="mt-1 text-sm text-text-md">Elevated with a soft shadow.</p>
+        </Card>
+      </Section>
+    </main>
+  );
+}
diff --git a/apps/planner/app/styles.css b/apps/planner/app/styles.css
index 8eff5ef..a6335a7 100644
--- a/apps/planner/app/styles.css
+++ b/apps/planner/app/styles.css
@@ -1,6 +1,9 @@
 @import "tailwindcss";
 @import "@trails-cool/ui/theme.css";
 
+/* Scan the shared UI package so its token utility classes are generated. */
+@source "../../../packages/ui/src";
+
 @keyframes slide {
   0% { transform: translateX(-100%); }
   100% { transform: translateX(400%); }
diff --git a/packages/ui/package.json b/packages/ui/package.json
index fb62fe5..45e622b 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -3,10 +3,28 @@
   "version": "0.0.1",
   "type": "module",
   "exports": {
+    ".": "./src/index.ts",
     "./theme.css": "./src/theme.css"
   },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "test": "vitest run",
+    "lint": "eslint .",
+    "typecheck": "tsc"
+  },
   "dependencies": {
     "@fontsource-variable/geist-mono": "catalog:",
     "@fontsource-variable/outfit": "catalog:"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:"
   }
 }
diff --git a/packages/ui/src/Badge.test.tsx b/packages/ui/src/Badge.test.tsx
new file mode 100644
index 0000000..ea97fc1
--- /dev/null
+++ b/packages/ui/src/Badge.test.tsx
@@ -0,0 +1,22 @@
+// @vitest-environment jsdom
+import { describe, it, expect, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { Badge } from "./Badge.tsx";
+
+afterEach(cleanup);
+
+describe("Badge", () => {
+  it("renders neutral tone by default", () => {
+    render(<Badge>New</Badge>);
+    const badge = screen.getByText("New");
+    expect(badge.className).toContain("bg-bg-subtle");
+    expect(badge.className).toContain("text-text-md");
+  });
+
+  it("applies the stop tone for overnight markers", () => {
+    render(<Badge tone="stop">NIGHT</Badge>);
+    const badge = screen.getByText("NIGHT");
+    expect(badge.className).toContain("bg-stop-bg");
+    expect(badge.className).toContain("text-stop");
+  });
+});
diff --git a/packages/ui/src/Badge.tsx b/packages/ui/src/Badge.tsx
new file mode 100644
index 0000000..f1bbccc
--- /dev/null
+++ b/packages/ui/src/Badge.tsx
@@ -0,0 +1,21 @@
+import type { HTMLAttributes } from "react";
+import { cn } from "./cn.ts";
+
+export type BadgeTone = "neutral" | "accent" | "stop";
+
+export interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
+  tone?: BadgeTone;
+}
+
+const base =
+  "inline-flex items-center gap-1 rounded-full px-2 py-0.5 text-xs font-medium";
+
+const tones: Record<BadgeTone, string> = {
+  neutral: "bg-bg-subtle text-text-md",
+  accent: "bg-accent-bg text-accent",
+  stop: "bg-stop-bg text-stop",
+};
+
+export function Badge({ tone = "neutral", className, ...props }: BadgeProps) {
+  return <span className={cn(base, tones[tone], className)} {...props} />;
+}
diff --git a/packages/ui/src/Button.test.tsx b/packages/ui/src/Button.test.tsx
new file mode 100644
index 0000000..cf6037a
--- /dev/null
+++ b/packages/ui/src/Button.test.tsx
@@ -0,0 +1,55 @@
+// @vitest-environment jsdom
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+import { Button } from "./Button.tsx";
+
+afterEach(cleanup);
+
+describe("Button", () => {
+  it("renders its children and defaults to type=button", () => {
+    render(<Button>Save</Button>);
+    const btn = screen.getByRole("button", { name: "Save" });
+    expect(btn).toHaveProperty("type", "button");
+  });
+
+  it("applies the primary variant token classes by default", () => {
+    render(<Button>Go</Button>);
+    const btn = screen.getByRole("button", { name: "Go" });
+    expect(btn.className).toContain("bg-accent");
+    expect(btn.className).toContain("text-text-inv");
+  });
+
+  it("switches variant and size classes", () => {
+    render(
+      <Button variant="ghost" size="sm">
+        Cancel
+      </Button>,
+    );
+    const btn = screen.getByRole("button", { name: "Cancel" });
+    expect(btn.className).toContain("text-text-md");
+    expect(btn.className).toContain("h-7");
+    expect(btn.className).not.toContain("bg-accent");
+  });
+
+  it("merges a caller className without dropping base classes", () => {
+    render(<Button className="w-full">Wide</Button>);
+    const btn = screen.getByRole("button", { name: "Wide" });
+    expect(btn.className).toContain("w-full");
+    expect(btn.className).toContain("rounded-md");
+  });
+
+  it("fires onClick and blocks it when disabled", () => {
+    const onClick = vi.fn();
+    const { rerender } = render(<Button onClick={onClick}>Tap</Button>);
+    fireEvent.click(screen.getByRole("button", { name: "Tap" }));
+    expect(onClick).toHaveBeenCalledTimes(1);
+
+    rerender(
+      <Button onClick={onClick} disabled>
+        Tap
+      </Button>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Tap" }));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/ui/src/Button.tsx b/packages/ui/src/Button.tsx
new file mode 100644
index 0000000..b11663c
--- /dev/null
+++ b/packages/ui/src/Button.tsx
@@ -0,0 +1,44 @@
+import type { ButtonHTMLAttributes } from "react";
+import { cn } from "./cn.ts";
+
+export type ButtonVariant = "primary" | "secondary" | "ghost";
+export type ButtonSize = "sm" | "md";
+
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+}
+
+const base =
+  "inline-flex items-center justify-center gap-1.5 rounded-md font-medium " +
+  "transition-colors focus-visible:outline-none focus-visible:ring-2 " +
+  "focus-visible:ring-accent focus-visible:ring-offset-1 focus-visible:ring-offset-bg " +
+  "disabled:pointer-events-none disabled:opacity-50";
+
+const variants: Record<ButtonVariant, string> = {
+  primary: "bg-accent text-text-inv hover:bg-accent-dim",
+  secondary:
+    "border border-border bg-bg-raised text-text-hi hover:bg-bg-subtle",
+  ghost: "text-text-md hover:bg-bg-subtle hover:text-text-hi",
+};
+
+const sizes: Record<ButtonSize, string> = {
+  sm: "h-7 px-2.5 text-xs",
+  md: "h-9 px-3.5 text-sm",
+};
+
+export function Button({
+  variant = "primary",
+  size = "md",
+  className,
+  type = "button",
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      type={type}
+      className={cn(base, variants[variant], sizes[size], className)}
+      {...props}
+    />
+  );
+}
diff --git a/packages/ui/src/Card.test.tsx b/packages/ui/src/Card.test.tsx
new file mode 100644
index 0000000..4c74e5b
--- /dev/null
+++ b/packages/ui/src/Card.test.tsx
@@ -0,0 +1,22 @@
+// @vitest-environment jsdom
+import { describe, it, expect, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { Card } from "./Card.tsx";
+
+afterEach(cleanup);
+
+describe("Card", () => {
+  it("renders a subtle surface by default", () => {
+    render(<Card>body</Card>);
+    const card = screen.getByText("body");
+    expect(card.className).toContain("bg-bg-subtle");
+    expect(card.className).not.toContain("shadow-sm");
+  });
+
+  it("renders a raised surface with a shadow when raised", () => {
+    render(<Card raised>panel</Card>);
+    const card = screen.getByText("panel");
+    expect(card.className).toContain("bg-bg-raised");
+    expect(card.className).toContain("shadow-sm");
+  });
+});
diff --git a/packages/ui/src/Card.tsx b/packages/ui/src/Card.tsx
new file mode 100644
index 0000000..a885335
--- /dev/null
+++ b/packages/ui/src/Card.tsx
@@ -0,0 +1,20 @@
+import type { HTMLAttributes } from "react";
+import { cn } from "./cn.ts";
+
+export interface CardProps extends HTMLAttributes<HTMLDivElement> {
+  /** Raised surface with a soft shadow (topbar/sidebar panels). */
+  raised?: boolean;
+}
+
+export function Card({ raised = false, className, ...props }: CardProps) {
+  return (
+    <div
+      className={cn(
+        "rounded-lg border border-border p-4",
+        raised ? "bg-bg-raised shadow-sm" : "bg-bg-subtle",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
diff --git a/packages/ui/src/Input.test.tsx b/packages/ui/src/Input.test.tsx
new file mode 100644
index 0000000..cf6f583
--- /dev/null
+++ b/packages/ui/src/Input.test.tsx
@@ -0,0 +1,26 @@
+// @vitest-environment jsdom
+import { describe, it, expect, afterEach } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+import { Input } from "./Input.tsx";
+
+afterEach(cleanup);
+
+describe("Input", () => {
+  it("defaults to type=text and forwards placeholder", () => {
+    render(<Input placeholder="Route name" />);
+    const input = screen.getByPlaceholderText("Route name");
+    expect(input).toHaveProperty("type", "text");
+    expect(input.className).toContain("border-border");
+  });
+
+  it("is controllable and forwards value changes", () => {
+    const values: string[] = [];
+    render(
+      <Input value="" onChange={(e) => values.push(e.currentTarget.value)} />,
+    );
+    fireEvent.change(screen.getByRole("textbox"), {
+      target: { value: "Alps" },
+    });
+    expect(values).toEqual(["Alps"]);
+  });
+});
diff --git a/packages/ui/src/Input.tsx b/packages/ui/src/Input.tsx
new file mode 100644
index 0000000..f5ce95c
--- /dev/null
+++ b/packages/ui/src/Input.tsx
@@ -0,0 +1,15 @@
+import type { InputHTMLAttributes } from "react";
+import { cn } from "./cn.ts";
+
+export type InputProps = InputHTMLAttributes<HTMLInputElement>;
+
+const base =
+  "h-9 w-full rounded-md border border-border bg-bg-raised px-3 text-sm " +
+  "text-text-hi placeholder:text-text-lo transition-colors " +
+  "focus-visible:border-accent focus-visible:outline-none " +
+  "focus-visible:ring-2 focus-visible:ring-accent-border " +
+  "disabled:cursor-not-allowed disabled:opacity-50";
+
+export function Input({ className, type = "text", ...props }: InputProps) {
+  return <input type={type} className={cn(base, className)} {...props} />;
+}
diff --git a/packages/ui/src/cn.ts b/packages/ui/src/cn.ts
new file mode 100644
index 0000000..1561029
--- /dev/null
+++ b/packages/ui/src/cn.ts
@@ -0,0 +1,4 @@
+/** Join class names, dropping falsy values. Tiny, dependency-free. */
+export function cn(...parts: Array<string | false | null | undefined>): string {
+  return parts.filter(Boolean).join(" ");
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
new file mode 100644
index 0000000..7d9e600
--- /dev/null
+++ b/packages/ui/src/index.ts
@@ -0,0 +1,9 @@
+export { cn } from "./cn.ts";
+export { Button } from "./Button.tsx";
+export type { ButtonProps, ButtonVariant, ButtonSize } from "./Button.tsx";
+export { Badge } from "./Badge.tsx";
+export type { BadgeProps, BadgeTone } from "./Badge.tsx";
+export { Card } from "./Card.tsx";
+export type { CardProps } from "./Card.tsx";
+export { Input } from "./Input.tsx";
+export type { InputProps } from "./Input.tsx";
diff --git a/packages/ui/tsconfig.json b/packages/ui/tsconfig.json
new file mode 100644
index 0000000..e9e15c2
--- /dev/null
+++ b/packages/ui/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "noEmit": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "build", "dist"]
+}
diff --git a/packages/ui/vitest.config.ts b/packages/ui/vitest.config.ts
new file mode 100644
index 0000000..8a07b14
--- /dev/null
+++ b/packages/ui/vitest.config.ts
@@ -0,0 +1 @@
+export { default } from "../../vitest.shared.ts";
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 33e60ef..38b7a10 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -691,6 +691,19 @@ importers:
       '@fontsource-variable/outfit':
         specifier: 'catalog:'
         version: 5.2.8
+    devDependencies:
+      '@types/react':
+        specifier: 'catalog:'
+        version: 19.2.17
+      '@types/react-dom':
+        specifier: 'catalog:'
+        version: 19.2.3(@types/react@19.2.17)
+      react:
+        specifier: ^19.2.5
+        version: 19.2.7
+      react-dom:
+        specifier: ^19.2.7
+        version: 19.2.7(react@19.2.7)
 
   scripts:
     devDependencies: