# UI Adapter Migration Playbook Use this when moving UI primitives toward `packages/ui` hotswap-ready adapters. ## Goal App code should eventually depend on stable adapter contracts such as `@toolctrl/ui/buttons`, not directly on a specific library implementation. Migration happens category by category. ## Migration Order 1. Navigation and shell 2. Buttons 3. Dialogs and modals 4. Tabs and tables 5. Inputs 6. Feedback ## Adapter Levels - `placeholder`: category exists but exports no real adapter contract. - `available`: package exposes stable metadata/contract for the current implementation. - `component-backed`: package exports real reusable components or wrappers. - `migrated`: app imports use the package adapter instead of app-local primitives. Current status: - `buttons`: `available` contract for `Button` and `buttonVariants`. - `layout`: `available` contract for `ShadcnSidebarLayout` and `UiRegistry`. - `navigation`: `available` contract for `AppSidebar`, `AdminSidebar`, `DocsSidebar`, `NavMain`, `NavSecondary`, `NavQuickLinks`, `NavActions`, and `SidebarPrimitives`. - all other categories: placeholder registry. ## Rules - Start with metadata/contract exports before moving components. - Keep adapter exports source-only and runtime-safe. - Keep runtime components in `apps/web/app/` until a migration phase explicitly moves imports. - Do not import app routes, data loaders, tenant context, admin context, or feature modules into `packages/ui`. - Do not hide feature-specific behavior inside `packages/ui`. - Keep shadcn/Radix as the current core default until a category-specific migration says otherwise. - Treat Headless UI as legacy unless explicitly retained by a category decision. ## Required Checks For each category migration: - Update `packages/ui/README.md`. - Update the relevant `packages/ui/src/.ts`. - Update `docs/ui-inventory/components.json`. - Add or update adapter contract tests. - Keep app imports unchanged unless the phase explicitly migrates them. ## Button Example Current button adapter contract: - `@toolctrl/ui/buttons` - `buttonAdapterNames` - `buttonAdapters` - source: `apps/web/app/components/ui/button.tsx` This records stable intent without moving the current shadcn implementation yet. ## Shell/Navigation Example Current shell/navigation adapter contracts: - `@toolctrl/ui/layout` - `layoutAdapterNames` - `layoutAdapters` - `@toolctrl/ui/navigation` - `navigationAdapterNames` - `navigationAdapters` These records point agents to the current runtime sources in `apps/web/app/` and are guarded by `apps/web/app/application/ui/uiAdapters.test.ts` plus the inventory tests.