@elabs-ai/components-ui 4.0.0 → 4.1.0

package/src/components/workspace-picker/workspace-picker.test.tsx

@@ -0,0 +1,207 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { WorkspacePicker } from "./workspace-picker";
+import { formatLastOpened } from "./workspace-picker-state";
+import type { Workspace } from "./workspace-picker-state";
+
+afterEach(cleanup);
+
+// cmdk calls Element.scrollIntoView to keep the auto-highlighted item visible.
+// jsdom doesn't implement it and this package's vitest setup deliberately ships
+// no global stub, so third-party libraries that don't feature-detect get a
+// local, scoped stub — the same pattern as model-picker.test.tsx and
+// combobox.test.tsx.
+let originalScrollIntoView: typeof Element.prototype.scrollIntoView;
+beforeEach(() => {
+  originalScrollIntoView = Element.prototype.scrollIntoView;
+  Element.prototype.scrollIntoView = vi.fn();
+});
+afterEach(() => {
+  Element.prototype.scrollIntoView = originalScrollIntoView;
+});
+
+// No `LocaleProvider` wrapper: `useLocale()` falls back to the shipped English
+// defaults, so these assertions prove the real `ui.workspacePicker.*` catalogue in
+// `packages/ui/src/components/locale-provider/messages.ts` rather than a local stub
+// that would keep passing if the central entry were missing or misspelled.
+function renderPicker(ui: React.ReactElement) {
+  return render(ui);
+}
+
+const workspaces: Workspace[] = [
+  {
+    id: "ws-1",
+    name: "elabs-components",
+    path: "~/dev/elabs-components",
+    lastOpenedAt: new Date(Date.now() - 2 * 60 * 60 * 1000),
+  },
+  {
+    id: "ws-2",
+    name: "brainless",
+    path: "~/dev/brainless",
+  },
+];
+
+const open = async () => {
+  await userEvent.click(screen.getAllByRole("combobox")[0]!);
+};
+
+describe("formatLastOpened", () => {
+  const now = Date.parse("2026-09-01T12:00:00.000Z");
+
+  it("picks minutes for recent times", () => {
+    expect(formatLastOpened(new Date(now - 5 * 60 * 1000), "en-US", now)).toBe("5 minutes ago");
+  });
+
+  it("picks hours once minutes would read awkwardly large", () => {
+    expect(formatLastOpened(new Date(now - 3 * 60 * 60 * 1000), "en-US", now)).toBe("3 hours ago");
+  });
+
+  it("picks days once hours would read awkwardly large", () => {
+    expect(formatLastOpened(new Date(now - 2 * 24 * 60 * 60 * 1000), "en-US", now)).toBe(
+      "2 days ago",
+    );
+  });
+
+  it("formats a future time as relative-forward", () => {
+    expect(formatLastOpened(new Date(now + 10 * 60 * 1000), "en-US", now)).toBe("in 10 minutes");
+  });
+});
+
+describe("WorkspacePicker", () => {
+  it("renders each workspace's path as truncating secondary text", async () => {
+    renderPicker(<WorkspacePicker workspaces={workspaces} />);
+    await open();
+    const description = screen.getByText("~/dev/elabs-components");
+    expect(description).toBeInTheDocument();
+    expect(description).toHaveClass("truncate");
+  });
+
+  it("marks the current workspace in the row's accessible name, not only by icon", async () => {
+    renderPicker(<WorkspacePicker workspaces={workspaces} currentId="ws-1" />);
+    await open();
+    const current = screen.getByRole("option", { name: /elabs-components/ });
+    const other = screen.getByRole("option", { name: /brainless/ });
+    expect(current).toHaveAccessibleName(/current/i);
+    expect(other).not.toHaveAccessibleName(/current/i);
+  });
+
+  it("names the trigger from the current workspace, and falls back to a placeholder", async () => {
+    const { unmount } = renderPicker(<WorkspacePicker workspaces={workspaces} currentId="ws-1" />);
+    expect(screen.getByRole("combobox")).toHaveTextContent("elabs-components");
+    unmount();
+
+    renderPicker(<WorkspacePicker workspaces={workspaces} />);
+    expect(screen.getByRole("combobox")).toHaveTextContent("No workspace selected");
+  });
+
+  it("reports the whole Workspace object on selection, not just the id", async () => {
+    const onSelect = vi.fn();
+    renderPicker(<WorkspacePicker workspaces={workspaces} onSelect={onSelect} />);
+    await open();
+    await userEvent.click(screen.getByText("brainless"));
+    expect(onSelect).toHaveBeenCalledTimes(1);
+    expect(onSelect).toHaveBeenCalledWith(workspaces[1]);
+  });
+
+  it("shows a designed empty state whose one action is the free-text path entry", async () => {
+    renderPicker(<WorkspacePicker workspaces={[]} onSubmitPath={vi.fn()} />);
+    await open();
+    // ModelPicker's own empty panel — reused, not reimplemented.
+    expect(screen.getByText("Nothing to show yet")).toBeInTheDocument();
+    expect(screen.queryByRole("option")).not.toBeInTheDocument();
+    // The action: the free-text path entry always renders, even with zero rows.
+    expect(screen.getByPlaceholderText("/path/to/project…")).toBeInTheDocument();
+  });
+
+  it("validates non-empty free text before reporting the raw string", async () => {
+    const onSubmitPath = vi.fn();
+    renderPicker(<WorkspacePicker workspaces={workspaces} onSubmitPath={onSubmitPath} />);
+    await open();
+    const submit = screen.getByRole("button", { name: "Open" });
+
+    await userEvent.click(submit);
+    expect(onSubmitPath).not.toHaveBeenCalled();
+
+    const input = screen.getByPlaceholderText("/path/to/project…");
+    await userEvent.type(input, "  ");
+    await userEvent.click(submit);
+    expect(onSubmitPath).not.toHaveBeenCalled();
+
+    await userEvent.clear(input);
+    await userEvent.type(input, "/tmp/new-workspace");
+    await userEvent.click(submit);
+    expect(onSubmitPath).toHaveBeenCalledTimes(1);
+    expect(onSubmitPath).toHaveBeenCalledWith("/tmp/new-workspace");
+  });
+
+  it("performs no filesystem access — onSubmitPath is the only side effect of a submit", async () => {
+    const onSubmitPath = vi.fn();
+    const onSelect = vi.fn();
+    renderPicker(
+      <WorkspacePicker workspaces={workspaces} onSubmitPath={onSubmitPath} onSelect={onSelect} />,
+    );
+    await open();
+    const input = screen.getByPlaceholderText("/path/to/project…");
+    await userEvent.type(input, "/tmp/new-workspace");
+    await userEvent.click(screen.getByRole("button", { name: "Open" }));
+    expect(onSubmitPath).toHaveBeenCalledWith("/tmp/new-workspace");
+    expect(onSelect).not.toHaveBeenCalled();
+    // The field clears after a successful submit.
+    expect(input).toHaveValue("");
+  });
+
+  it("submits the path on Enter instead of cmdk hijacking it as list navigation", async () => {
+    const onSubmitPath = vi.fn();
+    const onSelect = vi.fn();
+    renderPicker(
+      <WorkspacePicker workspaces={workspaces} onSubmitPath={onSubmitPath} onSelect={onSelect} />,
+    );
+    await open();
+    const input = screen.getByPlaceholderText("/path/to/project…");
+    await userEvent.type(input, "/tmp/other-workspace{Enter}");
+    expect(onSubmitPath).toHaveBeenCalledWith("/tmp/other-workspace");
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+
+  it("truncates a very long path without overflow", async () => {
+    const longPath = "~/dev/" + "very-long-segment/".repeat(20) + "elabs-components";
+    renderPicker(
+      <WorkspacePicker workspaces={[{ id: "ws-long", name: "long-one", path: longPath }]} />,
+    );
+    await open();
+    const description = screen.getByText(longPath);
+    expect(description).toHaveClass("truncate");
+    // The truncating span is a min-w-0 flex child — the min-w-0 + flex-1 rule
+    // that lets truncate actually clip instead of overflowing.
+    expect(description.parentElement).toHaveClass("min-w-0");
+  });
+
+  it("uses the caller's explicit aria-label over the default", async () => {
+    renderPicker(<WorkspacePicker workspaces={workspaces} aria-label="Session workspace" />);
+    expect(screen.getByRole("combobox")).toHaveAccessibleName("Session workspace");
+  });
+
+  it("renders the shipped English default with no LocaleProvider mounted", () => {
+    // No provider: `t()` falls back to `DEFAULT_MESSAGES[key] ?? key`. The keys
+    // landed in messages.ts with this component, so the fallback is now real
+    // microcopy — a regression that dropped them would surface here as the raw
+    // key string instead.
+    render(<WorkspacePicker workspaces={workspaces} />);
+    expect(screen.getByRole("combobox")).toHaveTextContent("No workspace selected");
+  });
+
+  it("scopes the workspace-picker data-slot to the root, distinct from model-picker", async () => {
+    const { container } = renderPicker(<WorkspacePicker workspaces={workspaces} />);
+    expect(container.querySelector('[data-slot="workspace-picker"]')).toBeInTheDocument();
+    expect(container.querySelector('[data-slot="model-picker"]')).not.toBeInTheDocument();
+  });
+
+  it("renders the free-text path form outside CommandList — the search query cannot hide it", async () => {
+    renderPicker(<WorkspacePicker workspaces={workspaces} />);
+    await open();
+    await userEvent.type(screen.getByPlaceholderText("Search workspaces…"), "no-match-xyz");
+    expect(screen.getByPlaceholderText("/path/to/project…")).toBeInTheDocument();
+  });
+});

package/src/components/workspace-picker/workspace-picker.tsx

@@ -0,0 +1,172 @@
+"use client";
+
+import { forwardRef, useState, type FormEvent, type HTMLAttributes } from "react";
+import { cn } from "../../lib/cn";
+import { Button } from "../button";
+import { Input } from "../input";
+import { useLocale } from "../locale-provider";
+import { ModelPicker, type ModelPickerGroup, type ModelPickerStatus } from "../model-picker";
+import { formatLastOpened, type Workspace } from "./workspace-picker-state";
+
+export type { Workspace };
+
+export interface WorkspacePickerProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
+  /** Recent workspaces, most-relevant first — the caller owns ordering. */
+  workspaces: Workspace[];
+  /** The currently open workspace's id. */
+  currentId?: string;
+  /** Fires with the chosen workspace; the popover closes first. */
+  onSelect?: (workspace: Workspace) => void;
+  /**
+   * Free-text path entry, rendered in `ModelPicker`'s `footer` slot below the
+   * list. Fires with the raw string the user typed once it validates as
+   * non-empty — this component performs no filesystem access of any kind
+   * (presentation layer, D5); resolving, normalizing or checking the path is
+   * the caller's job.
+   */
+  onSubmitPath?: (path: string) => void;
+  /**
+   * Drives the same four-body state grid as `ModelPicker` — see
+   * `ModelPickerStatus`. Default `"ready"`, inherited from `ModelPicker`.
+   */
+  status?: ModelPickerStatus;
+  disabled?: boolean;
+  /** Accessible name for the trigger and the popover — what the control is FOR. */
+  "aria-label"?: string;
+  /** Controlled popover open state — see `ModelPicker`'s controlled contract. */
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}
+
+/**
+ * Recent-workspace switcher — issue #111, decided in
+ * `docs/decisions/2026-09-01-brainless-adoption-architecture.md` § 7.
+ *
+ * A `ModelPicker` PRESET, not a new picker: `ModelPickerItem`'s
+ * `id`/`label`/`description`/`meta` shape is already a superset of what a
+ * workspace needs, so this component only supplies workspace-shaped
+ * defaults — it maps `path` into the truncating `description` slot, formats
+ * `lastOpenedAt` with `Intl.RelativeTimeFormat`, marks the current workspace
+ * in the row's TEXT (never colour alone — `ModelPicker`'s check glyph is
+ * `aria-hidden` and cannot carry that on its own), and renders the free-text
+ * path entry into `ModelPicker`'s `footer` slot so it sits below the list,
+ * un-filtered by the search query.
+ *
+ * Unlike `TeamSwitcher`, this has no `Sidebar` dependency — it works anywhere
+ * a picker is needed (a session launch card, a command palette), not only
+ * inside a sidebar.
+ */
+export const WorkspacePicker = forwardRef<HTMLDivElement, WorkspacePickerProps>(
+  function WorkspacePicker(
+    {
+      workspaces,
+      currentId,
+      onSelect,
+      onSubmitPath,
+      status,
+      disabled,
+      className,
+      open,
+      onOpenChange,
+      "aria-label": ariaLabelProp,
+      ...props
+    },
+    ref,
+  ) {
+    const { t, locale } = useLocale();
+    const [path, setPath] = useState("");
+
+    const current = workspaces.find((workspace) => workspace.id === currentId);
+    const triggerLabel = current?.name ?? t("ui.workspacePicker.placeholder");
+    const ariaLabel = ariaLabelProp ?? t("ui.workspacePicker.label");
+
+    const group: ModelPickerGroup = {
+      key: "workspaces",
+      label: t("ui.workspacePicker.recent"),
+      items: workspaces.map((workspace) => {
+        const isCurrent = workspace.id === currentId;
+        const meta: string[] = [];
+        if (workspace.lastOpenedAt) {
+          meta.push(formatLastOpened(workspace.lastOpenedAt, locale));
+        }
+        // Marked in TEXT so the marker reaches the row's accessible name and
+        // survives greyscale (accessibility.md's colour-is-never-the-only-
+        // channel test) — ModelPicker's own check glyph is `aria-hidden` and
+        // cannot carry this alone.
+        if (isCurrent) meta.push(t("ui.workspacePicker.current"));
+        return {
+          id: workspace.id,
+          label: workspace.name,
+          description: workspace.path,
+          meta,
+        };
+      }),
+    };
+
+    const handleSelect = (item: { id: string }) => {
+      const workspace = workspaces.find((w) => w.id === item.id);
+      if (workspace) onSelect?.(workspace);
+    };
+
+    const handleSubmit = (event: FormEvent<HTMLFormElement>) => {
+      event.preventDefault();
+      if (path.trim() === "") return;
+      onSubmitPath?.(path);
+      setPath("");
+    };
+
+    return (
+      <ModelPicker
+        ref={ref}
+        data-slot="workspace-picker"
+        className={cn(className)}
+        groups={[group]}
+        value={currentId}
+        onSelect={handleSelect}
+        status={status}
+        triggerLabel={triggerLabel}
+        aria-label={ariaLabel}
+        searchPlaceholder={t("ui.workspacePicker.searchPlaceholder")}
+        disabled={disabled}
+        open={open}
+        onOpenChange={onOpenChange}
+        footer={
+          // Outside `CommandList` on purpose (ModelPicker's own contract): a
+          // persistent action row, never filtered by the search query and
+          // never part of cmdk's roving selection.
+          //
+          // `onKeyDown` stops propagation because cmdk binds ITS OWN keydown
+          // handler on the `Command` root and reacts to Enter/Home/End/
+          // ArrowUp/ArrowDown regardless of which descendant is focused —
+          // without this, pressing Enter here would move the list's
+          // highlight instead of submitting the path.
+          <form
+            data-slot="workspace-picker-path-form"
+            onSubmit={handleSubmit}
+            onKeyDown={(event) => event.stopPropagation()}
+            className="flex items-center gap-2 border-t p-2"
+          >
+            <Input
+              data-slot="workspace-picker-path-input"
+              value={path}
+              onChange={(event) => setPath(event.target.value)}
+              placeholder={t("ui.workspacePicker.pathPlaceholder")}
+              aria-label={t("ui.workspacePicker.pathLabel")}
+              className="h-8 min-w-0 flex-1"
+            />
+            <Button
+              type="submit"
+              size="sm"
+              variant="outline"
+              aria-disabled={path.trim() === ""}
+              data-slot="workspace-picker-path-submit"
+            >
+              {t("ui.workspacePicker.openPath")}
+            </Button>
+          </form>
+        }
+        {...props}
+      />
+    );
+  },
+);

package/src/illustrations/empty-list-illustration.tsx

@@ -0,0 +1,26 @@
+import { forwardRef } from "react";
+import { illustrationSvgProps, type IllustrationProps } from "./illustration-base";
+
+/**
+ * Empty list / zero-data-yet state. Three line-art rows read as "empty list"
+ * on their own silhouette — no accent mark, per the accent-semantics
+ * convention in `illustration-base.tsx` (#48 finding 1): a floating "add"
+ * badge here would repeat information the rows already supply, not add any.
+ */
+export const EmptyListIllustration = forwardRef<SVGSVGElement, IllustrationProps>(
+  function EmptyListIllustration({ size, className, ...props }, ref) {
+    return (
+      <svg
+        ref={ref}
+        {...illustrationSvgProps(size, className)}
+        data-slot="empty-list-illustration"
+        {...props}
+      >
+        <rect x="36" y="68" width="64" height="10" rx="5" />
+        <rect x="36" y="90" width="64" height="10" rx="5" />
+        <rect x="36" y="112" width="44" height="10" rx="5" />
+      </svg>
+    );
+  },
+);
+EmptyListIllustration.displayName = "EmptyListIllustration";

package/src/illustrations/error-illustration.tsx

@@ -0,0 +1,60 @@
+import { forwardRef } from "react";
+import {
+  illustrationSvgProps,
+  illustrationAccent,
+  type IllustrationProps,
+} from "./illustration-base";
+
+/**
+ * Recoverable-failure state. A line-art document split into two halves with a
+ * visible gap between them — distinguishable from `NoAccessIllustration`/
+ * `OfflineIllustration` by silhouette alone (a split document reads as
+ * "broken" even in greyscale), per the WCAG 1.4.1 "never color-only" rule.
+ * The exclamation mark IS meaning-bearing (per the accent-semantics
+ * convention in `illustration-base.tsx`, #48 finding 1) — it turns "torn
+ * document" into "warning", information the silhouette alone doesn't carry —
+ * so it stays, in the upper-right quadrant of the right-hand half, clear of
+ * both documents' outlines.
+ *
+ * Redrawn for #24 fix round 1 (P1-3) — the previous cracked-card + tiny alert
+ * triangle read as a lightning bolt or a broken-image placeholder and the
+ * triangle's exclamation collapsed to an illegible blob at 4rem.
+ *
+ * Redrawn again for #48 finding 3 — the mark previously sat at (76-84,
+ * 54-95), exactly where the two document halves' torn edges converge, so it
+ * read as a knot of overlapping lines rather than a "!". Moved to
+ * (98-113, 44-85), 8-15 units clear of the nearest tear line at every
+ * y-coordinate it spans.
+ */
+export const ErrorIllustration = forwardRef<SVGSVGElement, IllustrationProps>(
+  function ErrorIllustration({ size, className, ...props }, ref) {
+    return (
+      <svg
+        ref={ref}
+        {...illustrationSvgProps(size, className)}
+        data-slot="error-illustration"
+        {...props}
+      >
+        <path d="M36,32 L83.06,32 L71.29,55.16 L92.47,69.06 L66.59,92.24 L76,120 L36,120 Z" />
+        <path d="M124,36 L124,124 L84,124 L74.59,96.24 L100.47,73.06 L79.29,59.16 L91.06,36 Z" />
+        <rect
+          x="104"
+          y="46"
+          width="8"
+          height="24"
+          rx="4"
+          style={{ fill: illustrationAccent("var(--destructive-text)") }}
+          stroke="none"
+        />
+        <circle
+          cx="108"
+          cy="80"
+          r="5"
+          style={{ fill: illustrationAccent("var(--destructive-text)") }}
+          stroke="none"
+        />
+      </svg>
+    );
+  },
+);
+ErrorIllustration.displayName = "ErrorIllustration";

package/src/illustrations/first-run-illustration.tsx

@@ -0,0 +1,27 @@
+import { forwardRef } from "react";
+import { illustrationSvgProps, type IllustrationProps } from "./illustration-base";
+
+/**
+ * First-run / onboarding state. A line-art planted flag — reads as "start
+ * here" on its own silhouette, distinct from `SuccessIllustration`. No
+ * accent mark, per the accent-semantics convention in `illustration-base.tsx`
+ * (#48 finding 1): a decorative sparkle here would repeat information the
+ * flag already supplies, not add any.
+ */
+export const FirstRunIllustration = forwardRef<SVGSVGElement, IllustrationProps>(
+  function FirstRunIllustration({ size, className, ...props }, ref) {
+    return (
+      <svg
+        ref={ref}
+        {...illustrationSvgProps(size, className)}
+        data-slot="first-run-illustration"
+        {...props}
+      >
+        <line x1="64" y1="122" x2="64" y2="46" />
+        <path d="M64,46 L100,54 L86,64 L100,74 L64,82 Z" strokeLinejoin="round" />
+        <line x1="36" y1="122" x2="90" y2="122" />
+      </svg>
+    );
+  },
+);
+FirstRunIllustration.displayName = "FirstRunIllustration";

package/src/illustrations/illustration-base.tsx

@@ -0,0 +1,108 @@
+import type { SVGProps } from "react";
+import { cn } from "../lib/cn";
+
+/**
+ * Shared 160×160 canvas every illustration draws on. Keeping one constant
+ * means every illustration's hand-authored coordinates line up on the same
+ * grid — every subject's ink is drawn to fill an ~88×88 box centered at
+ * (80, 78) (#24 fix round 1, P1-1), so the seven read as one optically-sized
+ * family instead of varying 2.1× against each other.
+ */
+export const ILLUSTRATION_VIEW_BOX = "0 0 160 160";
+
+export interface IllustrationProps extends SVGProps<SVGSVGElement> {
+  /**
+   * Rendered width & height (any CSS length — pass a `rem` value to stay
+   * density/zoom-aware). Illustrations are drawn to read clearly from about
+   * `4rem` (64px) up to `10rem` (160px).
+   * @default "7rem"
+   */
+  size?: string | number;
+}
+
+/**
+ * The `<svg>`-level attributes every illustration shares: canvas, stroke
+ * defaults (`currentColor`, so it themes with whatever text color the caller
+ * or ambient context applies — e.g. `StatePanel` tints the error kind's slot
+ * `text-destructive`), rem-based sizing, and decorative a11y (`aria-hidden`,
+ * `role="presentation"`) — every illustration is decorative; the state's
+ * title/description text is the accessible content, never the artwork.
+ *
+ * Deliberately does NOT include `data-slot` — each illustration file declares
+ * its own `data-slot="<name>-illustration"` literal alongside this spread, so
+ * the stable-selector convention (`.claude/rules/component-api.md`) is
+ * visible per-component, not hidden behind a shared factory.
+ */
+export function illustrationSvgProps(size: string | number = "7rem", className?: string) {
+  return {
+    viewBox: ILLUSTRATION_VIEW_BOX,
+    width: size,
+    height: size,
+    fill: "none",
+    stroke: "currentColor",
+    strokeWidth: 4,
+    strokeLinecap: "round" as const,
+    strokeLinejoin: "round" as const,
+    "aria-hidden": true as const,
+    role: "presentation" as const,
+    focusable: "false" as const,
+    className: cn("shrink-0", className),
+  };
+}
+
+/**
+ * Accent-semantics convention (#48 finding 1): an illustration draws at most
+ * ONE accent mark (via `illustrationAccent()` below), and it exists ONLY
+ * when it carries information the silhouette (the `currentColor`-stroked
+ * subject) does not already supply on its own — never as ornamental
+ * flourish wearing a meaning-bearing token. Applied across the seven
+ * shipped illustrations:
+ * - **Meaning-bearing (kept):** the "×" that turns a magnifying glass into
+ *   "no results" (`NoResultsIllustration`), the keyhole that turns a padlock
+ *   body into "restricted" (`NoAccessIllustration`), the checkmark that
+ *   turns a bare ring into "success" (`SuccessIllustration`), the
+ *   exclamation that turns a torn document into "warning" rather than
+ *   merely "broken" (`ErrorIllustration`).
+ * - **Was decorative-only, removed (#48):** the "add" badge on
+ *   `EmptyListIllustration` (three rows already read as "empty list" on
+ *   their own), the sparkle on `FirstRunIllustration` (the planted flag
+ *   already reads as "start here"), and the broken-link fragments on
+ *   `OfflineIllustration` (a slashed cloud already reads as "disconnected" —
+ *   the universal "no signal" idiom). Their accent-free silhouettes carry
+ *   the full state alone, matching how `ErrorIllustration`'s silhouette
+ *   already did before this convention was written down.
+ * Every illustration is `aria-hidden` regardless (the state's title/
+ * description text is the ACCESSIBLE channel — see `illustrationSvgProps`
+ * below), so this is a visual-consistency rule, not an a11y requirement on
+ * its own; don't regress the silhouette-carries-meaning property while
+ * redrawing any of the four kept accents above.
+ */
+
+/**
+ * The custom property every illustration's single meaning-bearing accent
+ * reads through. `StatePanel` sets it on the illustration slot's wrapper for
+ * `kind="error"` (`var(--destructive-text)`) so the accent follows the
+ * panel's tint instead of staying pinned to one hue inside a re-colored slot
+ * (#24 fix round 1, P0-2) — without this, an illustration whose accent
+ * defaults to the brand hue renders a lime badge on a red error panel. Falls
+ * back to each illustration's own default hue when no ambient override is
+ * set.
+ */
+export const ILLUSTRATION_ACCENT_VAR = "--illustration-accent";
+
+/**
+ * Build the `style` value for an illustration's accent ink: honors the
+ * ambient `--illustration-accent` override when set, otherwise `fallback`.
+ * `fallback` must be the correct **mark rung** for the accent's hue — e.g.
+ * `var(--primary-text)` (NOT `var(--primary)`, a plate color that measures
+ * 1.42:1 on `--card` in the `light` theme — #24 fix round 1, P0-1; see
+ * `.claude/rules/styling-and-tokens.md` "Which status rung a graphical MARK
+ * reaches for"), `var(--success-text)` for a positive-outcome accent, or
+ * `var(--destructive-text)` for an error accent — the TEXT rung, deliberately
+ * distinct from the FILL rung (`--destructive`) `StatePanel` puts the
+ * SUBJECT on for `kind="error"`, so the two don't collapse onto one colour
+ * (#48 finding 2).
+ */
+export function illustrationAccent(fallback: string): string {
+  return `var(${ILLUSTRATION_ACCENT_VAR}, ${fallback})`;
+}