HiveGrid-Wireframes/hivegrid-cloud/docs/agent-playbooks/ui-adapter-migration.md

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/<category>.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.