# @toolctrl/ui

Source-only UI adapter boundary for future primitive migration.

This package intentionally does not replace existing app imports yet. Runtime components remain in `apps/web/app` until a category migration explicitly moves them. The adapter contracts live in `@toolctrl/ui/*` so agents can target stable names before runtime imports are migrated.

## Categories

| Category | Export | Intended ownership |
| --- | --- | --- |
| `buttons` | `@toolctrl/ui/buttons` | Button-like actions, icon buttons and grouped controls. |
| `inputs` | `@toolctrl/ui/inputs` | Text fields, selects, checkboxes, switches and form-adjacent controls. |
| `dialogs` | `@toolctrl/ui/dialogs` | Modals, alert dialogs, drawers, popovers and confirmation surfaces. |
| `tables` | `@toolctrl/ui/tables` | Data tables, row actions, pagination and empty states for tabular data. |
| `layout` | `@toolctrl/ui/layout` | Page shells, panels, stacks, grids, containers and spacing primitives. |
| `navigation` | `@toolctrl/ui/navigation` | Menus, tabs, breadcrumbs, sidebars and command/navigation affordances. |
| `feedback` | `@toolctrl/ui/feedback` | Toasts, alerts, progress, skeletons, badges and status indicators. |

## Current Usage

The package is runtime-safe and still source-only. `buttons`, `layout`, and `navigation` expose available adapter metadata for the current app-level implementation:

```ts
import { uiAdapterCategories } from "@toolctrl/ui";
import { buttonAdapters } from "@toolctrl/ui/buttons";
import { layoutAdapters } from "@toolctrl/ui/layout";
import { navigationAdapters } from "@toolctrl/ui/navigation";
```

`buttonAdapters` describes `Button` and `buttonVariants`. `layoutAdapters` describes `ShadcnSidebarLayout` and `UiRegistry`. `navigationAdapters` describes `AppSidebar`, `AdminSidebar`, `DocsSidebar`, `NavMain`, `NavSecondary`, `NavQuickLinks`, `NavActions`, and `SidebarPrimitives`.

These contracts do not render components, import React or alter app runtime behavior yet. Other category exports remain empty readonly registries until their migration phase.

## Migration Guidance

1. Keep current `apps/web/app/components` imports in place until a migration phase owns that category.
2. Migrate one category at a time, starting with leaf primitives that have low app-specific coupling.
3. Add concrete component exports to the matching category subpath, then re-export from `@toolctrl/ui` only when the API is stable.
4. Keep category exports backward-compatible once app code starts importing them.

See [docs/migration.md](./docs/migration.md) for the category migration checklist.