build(deps): replace ladle with storybook 10 as the component workbench

.storybook/main.ts

@@ -0,0 +1,19 @@
+import type { StorybookConfig } from "@storybook/react-vite";
+
+const config: StorybookConfig = {
+  stories: ["../stories/**/*.stories.@(ts|tsx)"],
+  // Stories argue state through separate exports, not knobs.
+  features: { controls: false },
+  framework: {
+    name: "@storybook/react-vite",
+    options: { builder: { viteConfigPath: "vite.stories.config.mjs" } },
+  },
+  core: {
+    disableTelemetry: true,
+    // Reachable through a tailnet proxy; Storybook overrides Vite's
+    // `server.allowedHosts`, so this lives here rather than in the Vite config.
+    allowedHosts: [".ts.net"],
+  },
+};
+
+export default config;

.storybook/preview.tsx

@@ -0,0 +1,31 @@
+import type { Decorator, Preview } from "@storybook/react-vite";
+
+import "../src/styles.css";
+
+// Flip the real `.dark`/`.light` class on `<html>` that `src/theme.css` keys
+// off, during render so a story's first paint uses the selected theme. Light
+// is pinned with `.light`: with neither class the tokens follow the OS.
+const applyTheme: Decorator = (Story, { globals }) => {
+  const dark = globals["theme"] === "dark";
+  document.documentElement.classList.toggle("dark", dark);
+  document.documentElement.classList.toggle("light", !dark);
+  return <Story />;
+};
+
+const preview: Preview = {
+  globalTypes: {
+    theme: {
+      description: "Theme",
+      toolbar: {
+        title: "Theme",
+        icon: "mirror",
+        items: ["light", "dark"],
+        dynamicTitle: true,
+      },
+    },
+  },
+  initialGlobals: { theme: "light" },
+  decorators: [applyTheme],
+};
+
+export default preview;

AGENTS.md

@@ -19,7 +19,7 @@ arrives as props.
 - `src/index.ts`: the hand-written root barrel.
 - `src/theme.css`, `src/styles.css`: tokens and keyframes; the prebuilt sheet
   entry.
-- `stories/`: Ladle stories, kept out of `src/` so they never ship in `dist/`.
+- `stories/`: Storybook stories, kept out of `src/` so they never ship in `dist/`.
 - `scripts/dep-guard.mjs`, `scripts/contrast-test.mjs`: the CI gates.
 - `scripts/test-dom-setup.ts`: happy-dom preload for unit tests (`bunfig.toml`).
 - `e2e/`: checks against the built package.

CONTRIBUTING.md

@@ -14,7 +14,7 @@ Contributors sign the [CLA](CLA.md) on their first PR; the CLA bot explains how.
 `bun run test:e2e` checks the built package: every `exports` target exists and the
 root entry loads under Node with every optional peer blocked, then packs the
 package into a Vite host and runs the Playwright specs in `e2e/` against it. Each
-scenario is a route in `e2e/fixtures.tsx`. The same run builds the Ladle stories
+scenario is a route in `e2e/fixtures.tsx`. The same run builds the Storybook stories
 and fails on any serious or critical axe violation in any story. Run `bun run build` first, and
 `bunx playwright install chromium` once. CI also runs `bun run contrast-test` (theme contrast floors, reads
 `dist/styles.css`) and `bun run dep-guard` (forbidden imports, see `AGENTS.md`)
@@ -26,7 +26,7 @@ Change tokens in `src/theme.css`, then run `bun run build`; `dist/` is generated
 A failing contrast pair prints `FAIL <ratio>:1 (>=<floor>) <mode> <pair>`. Fix it
 with a naming rule in `checksFor`, never a hardcoded hex pair.
 
-`bun run stories` starts the Ladle workbench over every component against
+`bun run stories` starts the Storybook workbench over every component against
 `src/theme.css`; `bun run stories:build` writes a static copy to `build/`. A new
 component ships with a story for each meaningful state (loading, empty, error).