feat: add react api and shadcn foundation

docs/superpowers/plans/2026-06-19-react-runtime-migration.md

@@ -6,7 +6,7 @@
 
 **Architecture:** The browser runtime becomes React mounted from `src/main.tsx`. A Bun server at `src/server/index.ts` serves the static React build and exposes JSON API routes for dashboard reads and agent dashboard mutations. Existing model, persistence, datasource, and agent-config modules remain framework-agnostic TypeScript with import path updates as needed.
 
-**Tech Stack:** Bun, Vite, React, React DOM, TypeScript, Vitest, Storybook React Vite, Playwright, Drizzle ORM, Bun SQLite, MSW, uPlot, Iconify React.
+**Tech Stack:** Bun, Vite, React, React DOM, TypeScript, Tailwind CSS v4, shadcn/ui, Vitest, Storybook React Vite, Playwright, Drizzle ORM, Bun SQLite, MSW, uPlot, Iconify React.
 
 ---
 
@@ -23,13 +23,16 @@
 - Create `src/server/routes/agent-dashboard.test.ts`: agent API delegation/auth tests.
 - Create `src/lib/ui/components/*.tsx`: React ports of current reusable Svelte components.
 - Create `src/lib/ui/components/styles.css`: component CSS migrated from Svelte style blocks.
+- Create `components.json`: shadcn/ui configuration for Vite, Radix, Nova, Tailwind v4, and `$lib` aliases.
+- Create `src/lib/components/ui/*.tsx`: selected shadcn primitives, not the full registry.
+- Create `src/lib/utils.ts`: `cn()` helper for shadcn and dashboard components.
 - Replace `src/lib/ui/components/render.test.ts`: React `renderToString` component tests.
 - Replace `src/lib/ui/stories/*.stories.svelte`: React `.stories.tsx` stories.
 - Modify `.storybook/main.ts`: use `@storybook/react-vite` and React story globs.
 - Modify `.storybook/preview.ts`: use React Storybook types and keep MSW setup/global CSS.
-- Modify `vite.config.ts`: use React plugin, alias `$lib` to `src/lib`, build client, and keep Vitest config.
+- Modify `vite.config.ts`: use React and Tailwind plugins, alias `$lib` to `src/lib`, build client, and keep Vitest config.
 - Modify `tsconfig.json`: remove `.svelte-kit` inheritance, enable JSX, and define path aliases.
-- Modify `package.json`: swap Svelte/SvelteKit dependencies for React tooling and update scripts.
+- Modify `package.json`: swap Svelte/SvelteKit dependencies for React/Tailwind/shadcn tooling and update scripts.
 - Modify `playwright.config.ts`: build React client and Bun server before e2e.
 - Modify `Containerfile`: copy React/Bun build artifacts and keep `bun build/index.js` command.
 - Modify `README.md`: document React runtime, Bun server, scripts, QA gate, deployment.
@@ -104,11 +107,12 @@ Update `package.json` scripts and dependencies:
 }
 ```
 
-Install React packages with Bun so `bun.lock` updates:
+Install React, Tailwind, and shadcn packages with Bun so `bun.lock` updates:
 
 ```sh
 bun add @iconify/react @vitejs/plugin-react react react-dom
-bun add -d @storybook/react-vite @types/react @types/react-dom
+bun add class-variance-authority clsx lucide-react radix-ui tailwind-merge tw-animate-css @fontsource-variable/geist
+bun add -d @storybook/react-vite @tailwindcss/vite @types/react @types/react-dom shadcn tailwindcss
 ```
 
 Create `index.html`:
@@ -181,7 +185,16 @@ createRoot(root).render(
 
 Update `tsconfig.json` with React JSX and path aliases.
 
-Update `vite.config.ts` to use `@vitejs/plugin-react` and `$lib` alias.
+Update `vite.config.ts` to use `@vitejs/plugin-react`, `@tailwindcss/vite`,
+and the `$lib` alias. Initialize shadcn with:
+
+```sh
+bunx --bun shadcn@latest init --template vite --base radix --preset nova --yes --css-variables
+bunx --bun shadcn@latest add badge card progress separator skeleton alert
+```
+
+Do not run `bunx --bun shadcn@latest add --all`; the dashboard should only
+vendor primitives it actually uses.
 
 - [ ] **Step 4: Run checks for the scaffold**
 

docs/superpowers/specs/2026-06-19-react-runtime-migration-design.md

@@ -18,7 +18,10 @@ state is a React runtime and React component library.
 
 Use Vite React for the browser app and a small Bun HTTP server for production
 runtime. This keeps the existing Bun SQLite persistence model and avoids adding
-a heavier React framework where the current route/API surface is small.
+a heavier React framework where the current route/API surface is small. Use
+Tailwind CSS v4 and shadcn/ui as the reusable primitive layer for React
+components, but do not vendor the full shadcn registry. Add only primitives
+that map to the dashboard surface.
 
 The migrated app will have these boundaries:
 
@@ -36,6 +39,10 @@ The migrated app will have these boundaries:
   TypeScript business logic with minimal import-path updates.
 - `src/lib/ui/components/*.tsx` contains the reusable React component library.
 - `src/lib/ui/stories/*.stories.tsx` contains React Storybook stories.
+- `src/lib/components/ui/*.tsx` contains shadcn/ui primitives used by the
+  dashboard component library.
+- `components.json` records the shadcn configuration with Vite, Radix, the Nova
+  preset, and `$lib` import aliases.
 
 ## Component Migration
 
@@ -76,10 +83,12 @@ data-model identifiers, severity attributes, focusable links, reduced-motion
 behavior, and screenshot-tested dashboard layout must stay equivalent to the
 current Svelte implementation.
 
-CSS will remain in `src/lib/ui/tokens.css` and component-specific CSS files.
-React components should import their own CSS modules or regular CSS files in a
-consistent local pattern. Shared UI types and `dashboardDocumentToUiDashboard`
-remain framework-agnostic TypeScript.
+CSS will keep the existing design tokens in `src/lib/ui/tokens.css`.
+`src/app.css` imports Tailwind, shadcn CSS, font assets, and the existing
+Dimension Lab token file. shadcn semantic variables must be mapped to the dark
+console palette so generated primitives fit the dashboard instead of resetting
+the app to a light generic theme. Shared UI types and
+`dashboardDocumentToUiDashboard` remain framework-agnostic TypeScript.
 
 ## Runtime And API Behavior
 
@@ -101,8 +110,11 @@ owned by `src/lib/server/agent-config/index.ts`.
 
 `package.json` will move from Svelte/SvelteKit dependencies to React tooling:
 
-- Runtime dependencies include `@vitejs/plugin-react`, `react`, `react-dom`,
-  `@iconify/react`, and existing non-Svelte libraries that still apply.
+- Runtime dependencies include `react`, `react-dom`, `@iconify/react`,
+  selected shadcn primitive dependencies, Tailwind merge helpers, and existing
+  non-Svelte libraries that still apply.
+- Dev dependencies include `@vitejs/plugin-react`, `@tailwindcss/vite`,
+  `tailwindcss`, and the shadcn package needed by the generated CSS import.
 - Storybook moves from `@storybook/sveltekit` and Svelte CSF to
   `@storybook/react-vite`.
 - `svelte.config.js`, `src/app.html`, `src/routes/**`, and `.svelte` files are
@@ -139,6 +151,8 @@ The migration is complete only when current evidence proves all of these:
 
 - There are no `.svelte` app, component, route, or story files left.
 - `package.json` has no Svelte, SvelteKit, or Svelte Storybook dependencies.
+- shadcn is configured for Vite/Radix with `$lib` aliases and only selected
+  primitives, not the full registry.
 - `bun run check` passes.
 - `bun run test:unit` passes.
 - `bun run build` produces the React client build and Bun server entry.