@elabs-ai/components-ui 4.0.0 → 4.2.0

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})`;
+}

package/src/illustrations/illustrations.stories.tsx

@@ -0,0 +1,94 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import type { ComponentType } from "react";
+import {
+  EmptyListIllustration,
+  NoResultsIllustration,
+  NoAccessIllustration,
+  ErrorIllustration,
+  OfflineIllustration,
+  SuccessIllustration,
+  FirstRunIllustration,
+  type IllustrationProps,
+} from "./index";
+
+/**
+ * Demo wrapper: illustrations are pure `currentColor` line art plus one
+ * meaning-bearing accent (`--primary-text` by default; `--success-text` on
+ * `SuccessIllustration`, `--destructive` on `ErrorIllustration`), so a story
+ * renders them inside a `text-muted-foreground` container — the same ambient
+ * color `StatePanel` applies via its icon/illustration slot. `StatePanel`
+ * retints the accent to `--destructive` for any illustration placed in a
+ * `kind="error"` slot via the `--illustration-accent` custom property (see
+ * `illustration-base.tsx`) — see `States/StatePanel`'s "Error (with
+ * illustration, #24 P0-2)" story for that pairing.
+ */
+function Demo(props: IllustrationProps & { as: ComponentType<IllustrationProps> }) {
+  const { as: Illustration, ...rest } = props;
+  return (
+    <div className="text-muted-foreground">
+      <Illustration {...rest} />
+    </div>
+  );
+}
+
+const meta = {
+  title: "States/Illustrations",
+  component: Demo,
+  tags: ["autodocs"],
+  argTypes: {
+    size: {
+      control: "text",
+      description: "Rendered width/height (any CSS length). Legible ~4rem–10rem.",
+    },
+  },
+} satisfies Meta<typeof Demo>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const EmptyList: Story = {
+  args: { as: EmptyListIllustration },
+};
+
+export const NoResults: Story = {
+  args: { as: NoResultsIllustration },
+};
+
+export const NoAccess: Story = {
+  args: { as: NoAccessIllustration },
+};
+
+export const Error: Story = {
+  args: { as: ErrorIllustration },
+};
+
+export const Offline: Story = {
+  args: { as: OfflineIllustration },
+};
+
+export const Success: Story = {
+  args: { as: SuccessIllustration },
+};
+
+export const FirstRun: Story = {
+  args: { as: FirstRunIllustration },
+};
+
+export const CustomSize: Story = {
+  name: "Custom size (10rem)",
+  args: { as: EmptyListIllustration, size: "10rem" },
+};
+
+export const AllStates: Story = {
+  name: "All seven, side by side",
+  render: () => (
+    <div className="flex flex-wrap gap-8 text-muted-foreground">
+      <EmptyListIllustration />
+      <NoResultsIllustration />
+      <NoAccessIllustration />
+      <ErrorIllustration />
+      <OfflineIllustration />
+      <SuccessIllustration />
+      <FirstRunIllustration />
+    </div>
+  ),
+};

package/src/illustrations/illustrations.test.tsx

@@ -0,0 +1,98 @@
+import type { CSSProperties } from "react";
+import { describe, expect, it } from "vitest";
+import { render } from "@testing-library/react";
+import {
+  EmptyListIllustration,
+  NoResultsIllustration,
+  NoAccessIllustration,
+  ErrorIllustration,
+  OfflineIllustration,
+  SuccessIllustration,
+  FirstRunIllustration,
+  ILLUSTRATION_ACCENT_VAR,
+  illustrationAccent,
+} from "./index";
+
+// No literal hex anywhere in a rendered attribute — only `currentColor` or a
+// `var(--…)` token reference (inline style or attribute) may carry color.
+const RAW_HEX_RE = /#[0-9a-fA-F]{3,6}\b/;
+
+const ILLUSTRATIONS = [
+  ["EmptyListIllustration", EmptyListIllustration, "empty-list-illustration"],
+  ["NoResultsIllustration", NoResultsIllustration, "no-results-illustration"],
+  ["NoAccessIllustration", NoAccessIllustration, "no-access-illustration"],
+  ["ErrorIllustration", ErrorIllustration, "error-illustration"],
+  ["OfflineIllustration", OfflineIllustration, "offline-illustration"],
+  ["SuccessIllustration", SuccessIllustration, "success-illustration"],
+  ["FirstRunIllustration", FirstRunIllustration, "first-run-illustration"],
+] as const;
+
+describe("state illustrations", () => {
+  it.each(ILLUSTRATIONS)(
+    "%s renders a decorative, token-driven <svg>",
+    (_name, Component, slot) => {
+      const { container } = render(<Component />);
+      const svg = container.querySelector("svg");
+      expect(svg).not.toBeNull();
+      expect(svg?.tagName.toLowerCase()).toBe("svg");
+      expect(svg).toHaveAttribute("aria-hidden", "true");
+      expect(svg).toHaveAttribute("role", "presentation");
+      expect(svg).toHaveAttribute("data-slot", slot);
+
+      // No raw hex anywhere in the tree's attributes (element attrs + style attr).
+      const offenders: string[] = [];
+      for (const el of Array.from(container.querySelectorAll("*"))) {
+        for (const attr of Array.from(el.attributes)) {
+          if (RAW_HEX_RE.test(attr.value)) {
+            offenders.push(`${el.tagName}[${attr.name}]="${attr.value}"`);
+          }
+        }
+      }
+      expect(offenders).toEqual([]);
+    },
+  );
+
+  it("accepts a custom `size` and applies it as width/height", () => {
+    const { container } = render(<EmptyListIllustration size="10rem" />);
+    const svg = container.querySelector("svg");
+    expect(svg).toHaveAttribute("width", "10rem");
+    expect(svg).toHaveAttribute("height", "10rem");
+  });
+
+  it("defaults to a rem-based size within the legible 64px–160px range", () => {
+    const { container } = render(<NoResultsIllustration />);
+    const svg = container.querySelector("svg");
+    const width = svg?.getAttribute("width") ?? "";
+    expect(width).toMatch(/rem$/);
+  });
+
+  it("merges a caller className without dropping the base classes", () => {
+    const { container } = render(<SuccessIllustration className="text-primary" />);
+    const svg = container.querySelector("svg");
+    expect(svg?.getAttribute("class")).toContain("text-primary");
+  });
+
+  // #12/#53 review (P2): `ILLUSTRATION_ACCENT_VAR` is the mechanism `StatePanel`
+  // uses internally to safely retint an illustration's meaning-bearing accent
+  // (see illustration-base.tsx). A consumer rendering an illustration OUTSIDE
+  // `StatePanel` needs the same seam without duplicating the private
+  // "--illustration-accent" string, so the barrel must export it.
+  it("exports ILLUSTRATION_ACCENT_VAR — the public retint seam for consumers outside StatePanel", () => {
+    expect(ILLUSTRATION_ACCENT_VAR).toBe("--illustration-accent");
+    // A consumer can set it inline exactly the way StatePanel does internally.
+    const { container } = render(
+      <div style={{ [ILLUSTRATION_ACCENT_VAR]: "var(--success-text)" } as CSSProperties}>
+        <SuccessIllustration />
+      </div>,
+    );
+    const wrapper = container.firstChild as HTMLElement;
+    expect(wrapper.style.getPropertyValue(ILLUSTRATION_ACCENT_VAR)).toBe("var(--success-text)");
+  });
+
+  it("exports illustrationAccent — the public helper for building an illustration's fallback stroke/fill color", () => {
+    const fallback = "var(--success-text)";
+    const result = illustrationAccent(fallback);
+    // illustrationAccent(fallback) returns var(--illustration-accent, fallback)
+    expect(result).toBe(`var(${ILLUSTRATION_ACCENT_VAR}, ${fallback})`);
+  });
+});

package/src/illustrations/index.ts

@@ -0,0 +1,16 @@
+export type { IllustrationProps } from "./illustration-base";
+// The custom-property name a consumer sets to safely retint an illustration's
+// meaning-bearing accent (see `StatePanel`'s own usage). Previously only the
+// illustration components + `IllustrationProps` were exported here, so a
+// consumer rendering an illustration OUTSIDE `StatePanel` had no way to reach
+// this seam without duplicating the private string (#12/#53 review, P2).
+// Relates to the wider "illustration customization" tracking issue #46 — this
+// change exports the existing constant, it does not itself resolve #46.
+export { ILLUSTRATION_ACCENT_VAR, illustrationAccent } from "./illustration-base";
+export { EmptyListIllustration } from "./empty-list-illustration";
+export { NoResultsIllustration } from "./no-results-illustration";
+export { NoAccessIllustration } from "./no-access-illustration";
+export { ErrorIllustration } from "./error-illustration";
+export { OfflineIllustration } from "./offline-illustration";
+export { SuccessIllustration } from "./success-illustration";
+export { FirstRunIllustration } from "./first-run-illustration";

package/src/illustrations/no-access-illustration.tsx

@@ -0,0 +1,45 @@
+import { forwardRef } from "react";
+import {
+  illustrationSvgProps,
+  illustrationAccent,
+  type IllustrationProps,
+} from "./illustration-base";
+
+/**
+ * Permission / access-denied state. A line-art padlock with a `--primary-text`
+ * keyhole — reads as "restricted", not "broken". The keyhole is meaning-bearing
+ * (per the accent-semantics convention in `illustration-base.tsx`, #48
+ * finding 1) — it's what distinguishes a padlock from a generic rounded box.
+ */
+export const NoAccessIllustration = forwardRef<SVGSVGElement, IllustrationProps>(
+  function NoAccessIllustration({ size, className, ...props }, ref) {
+    return (
+      <svg
+        ref={ref}
+        {...illustrationSvgProps(size, className)}
+        data-slot="no-access-illustration"
+        {...props}
+      >
+        <path d="M50,72 V52 A30,20 0 0 1 110,52 V72" />
+        <rect x="36" y="72" width="88" height="48" rx="10" />
+        <circle
+          cx="80"
+          cy="92"
+          r="6"
+          style={{ stroke: illustrationAccent("var(--primary-text)") }}
+          strokeWidth={3}
+        />
+        <rect
+          x="77"
+          y="98"
+          width="6"
+          height="12"
+          rx="2"
+          style={{ stroke: illustrationAccent("var(--primary-text)") }}
+          strokeWidth={3}
+        />
+      </svg>
+    );
+  },
+);
+NoAccessIllustration.displayName = "NoAccessIllustration";