{
  "id": "page:docs-superpowers-specs-2026-04-29-webui-compendium-migration-design",
  "_kind": "Page",
  "_file": "wiki/docs/superpowers/specs/2026-04-29-webui-compendium-migration-design.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/superpowers/specs/2026-04-29-webui-compendium-migration-design.md",
    "sourceKind": "repo-docs",
    "title": "WebUI Compendium Migration Design",
    "displayName": "WebUI Compendium Migration Design",
    "slug": "docs/superpowers/specs/2026-04-29-webui-compendium-migration-design",
    "articlePath": "wiki/docs/superpowers/specs/2026-04-29-webui-compendium-migration-design.md",
    "article": "\n# WebUI Compendium Migration Design\n\nMigrate the adapters webui from its current mixed styling system (Radix UI + Tailwind + hand-rolled CSS + partial compendium) to compendium as the sole design system. Remove the deprecated kanban package dependency. Fix all broken layouts, overlays, and usability issues.\n\n## Context\n\nThe webui has broken layouts on most pages, the command palette renders at the bottom instead of as a centered overlay, and there are pervasive design inconsistencies. Root cause: `kanban/globals.css` (950+ lines of duplicate/conflicting CSS) shadows compendium's design tokens, Radix UI wrappers duplicate compendium components, and Next.js shims exist for a kanban package that is being removed.\n\n## Architecture\n\nTwo layers after migration:\n\n- **Compendium** (`@a5c-ai/compendium`) — sole design system. All UI primitives (Button, Modal, Tabs, CommandPalette, Sidebar, Toast, etc.), design tokens, and component CSS.\n- **Webui** — owns all page components, hooks, services, and types. No kanban imports. No Radix UI. No Next.js shims.\n\n### Directory Structure\n\n```\nsrc/\n├── App.tsx\n├── main.tsx\n├── router.tsx                 # Routes + AppShell\n├── shell/\n│   ├── AppShell.tsx           # Sidebar + TopBar + content + CommandPalette\n│   ├── Sidebar.tsx            # Wraps compendium Sidebar/NavItem\n│   ├── TopBar.tsx             # Breadcrumbs + actions\n│   └── CommandPalette.tsx     # Wraps compendium CommandPalette\n├── pages/\n│   ├── projects/\n│   ├── runs/\n│   ├── sessions/\n│   ├── workspaces/\n│   ├── inbox/\n│   ├── automations/\n│   ├── agents/\n│   ├── settings/\n│   └── login/\n├── components/                # Domain-specific shared components\n│   ├── pipeline/\n│   ├── events/\n│   ├── details/\n│   ├── breakpoint/\n│   ├── notifications/\n│   └── review/\n├── hooks/\n├── lib/\n├── providers/\n├── types/\n└── styles/\n    └── app.css                # Compendium import + ~50 lines of app layout\n```\n\n### What Gets Deleted\n\n- `src/kanban/` — entire directory (globals.css, component re-exports, shims)\n- `src/kanban-shims/` — Next.js compatibility layer (next/link, next/navigation)\n- `src/kanban/components/ui/` — Radix wrappers replaced by compendium\n- `src/styles/global.css` — replaced by `app.css`\n\n## Shell & Overlay System\n\n### AppShell Layout\n\nReplaces the current `AppChrome` CSS grid with a simple flexbox layout.\n\n```tsx\n<div className=\"app-shell\">\n  <Sidebar>\n    <NavItem icon={...} href=\"/projects\">Projects</NavItem>\n    <NavItem icon={...} href=\"/runs\">Runs</NavItem>\n    <NavItem icon={...} href=\"/sessions\">Sessions</NavItem>\n    ...\n  </Sidebar>\n  <div className=\"app-main\">\n    <TopBar />\n    <main className=\"app-content\">\n      <Outlet />\n    </main>\n  </div>\n  <CommandPalette open={open} onClose={close} items={actions} onSelect={handler} />\n</div>\n```\n\n### Overlay System\n\nAll overlays use compendium's Portal → rendered at `document.body`:\n- Scrim: z-index 100, backdrop-filter blur\n- Modal/CommandPalette content: z-index 101\n- Toasts: z-index 120\n\nNo custom z-index values in webui CSS.\n\n### Mobile\n\nDrop the duplicate `webui-rail` bottom nav bar. Use compendium Sidebar's built-in collapse behavior. Single responsive breakpoint at 768px collapses sidebar.\n\n### CSS\n\nSingle file `styles/app.css` replaces both `kanban/globals.css` and `styles/global.css`:\n\n```css\n@import '@a5c-ai/compendium/css';\n\n.app-shell { display: flex; height: 100vh; }\n.app-main  { flex: 1; min-width: 0; display: flex; flex-direction: column; overflow-y: auto; }\n.app-content { padding: var(--tk-space-lg); max-width: 1200px; width: 100%; margin: 0 auto; }\n\n@media (max-width: 768px) {\n  .app-shell { flex-direction: column; }\n}\n```\n\nEverything else comes from compendium component classes.\n\n## Component Migration Map\n\n| Current | Compendium replacement |\n|---|---|\n| `@radix-ui/react-dialog` + `dialog-shell.tsx` | `Modal`, `Drawer` |\n| `@radix-ui/react-tabs` + `tabs.tsx` | `Tabs` |\n| `@radix-ui/react-accordion` + `accordion.tsx` | `Accordion` |\n| `@radix-ui/react-tooltip` + `tooltip.tsx` | `Tooltip` |\n| `@radix-ui/react-scroll-area` | Native `overflow-y: auto` |\n| `@radix-ui/react-separator` | `<hr className=\"tkc-rule\">` |\n| Custom `button.tsx` (CVA) | `Button`, `IconButton` |\n| Custom `card.tsx` | `.tkc-panel` class |\n| Custom `badge.tsx` / `status-badge.tsx` | `Tag` with variant |\n| Custom `settings-modal.tsx` | Content wrapped in `Modal` |\n| Custom `shortcuts-help.tsx` | Content wrapped in `Modal` |\n| Custom `page-shell.tsx` | Remove — AppShell handles layout |\n| Custom notification toasts | `ToastProvider` + `useToasts()` |\n| `cn()` (tailwind-merge + clsx) | `cx()` from compendium |\n\n### Unchanged\n\n- Services & hooks (business logic, not UI) — move from `kanban/hooks/` and `kanban/lib/` to `hooks/` and `lib/`\n- Zustand stores, gateway/auth flow, API layer\n- Routing structure (same URLs)\n- Specialized components (pipeline, events, JSON tree, agent panel) — keep structure, restyle with compendium tokens\n\n### Dependencies Removed\n\n- `@radix-ui/react-dialog`, `react-tabs`, `react-accordion`, `react-tooltip`, `react-scroll-area`, `react-separator`, `react-slot`\n- `tailwind-merge`, `class-variance-authority`, `clsx`\n- `tailwindcss`, `postcss`, `autoprefixer`\n\n## Migration Phases\n\nEach phase leaves the app in a working state.\n\n### Phase 1 — Shell replacement\n\nReplace AppChrome with AppShell. New `app.css` replaces both global CSS files. Sidebar, TopBar, CommandPalette rewired to compendium. Delete `webui-rail`. Fixes overlay/layout issues on every page immediately.\n\n### Phase 2 — UI primitive swap\n\nReplace Radix wrappers (`components/ui/`) with compendium imports. Button, Modal, Tabs, Accordion, Tooltip, Tag. Update all import paths. Delete `cn()`, switch to `cx()`. Remove Radix and Tailwind dependencies.\n\n### Phase 3 — Move kanban internals into webui\n\nMove hooks, services, types, and page components from `src/kanban/` to `src/hooks/`, `src/lib/`, `src/pages/`, `src/components/`. Delete Next.js shims. Delete `src/kanban/` and `src/kanban-shims/`.\n\n### Phase 4 — Restyle page components\n\nPage-by-page: replace Tailwind classes with compendium tokens on pipeline cards, event stream, JSON tree, dashboard grids, detail panels. Each page is independent.\n\n### Phase 5 — Cleanup & verify\n\nRemove Tailwind config files. Verify build. Test all routes. Verify dark/light theme toggle. Remove unused CSS.\n\n## Testing Strategy\n\n- After each phase: `npm run build` must succeed\n- Manual smoke test: login → navigate all pages → command palette (Cmd+K) → theme toggle → mobile viewport\n- Existing vitest tests updated as import paths change\n- No new test framework\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs",
      "to": "page:docs-superpowers-specs-2026-04-29-webui-compendium-migration-design",
      "kind": "contains_page"
    }
  ]
}