admin-ui-starter-kit 0.1.2 → 0.1.4

package/.agents/skills/component-library-rules/references/components/ui__toggles-group.md

@@ -39,7 +39,7 @@ export function SingleToggle() {
 	const [pressed, setPressed] = useState(false);
 	return (
 		<>
-			<Toggle pressed={pressed} onPressedChange={setPressed}>
+			<Toggle aria-label="Bold" pressed={pressed} onPressedChange={setPressed}>
 								<Bold />
 							</Toggle>
 		</>
@@ -51,12 +51,12 @@ export function MultipleSelectGroup() {
 	return (
 		<>
 			<ToggleGroup value={marks} onValueChange={setMarks}>
-								<ToggleGroupItem value="bold"><Bold /></ToggleGroupItem>
-								<ToggleGroupItem value="italic"><Italic /></ToggleGroupItem>
-								<ToggleGroupItem value="underline"><Underline /></ToggleGroupItem>
-								<ToggleGroupItem value="left"><AlignLeft /></ToggleGroupItem>
-								<ToggleGroupItem value="center"><AlignCenter /></ToggleGroupItem>
-								<ToggleGroupItem value="right"><AlignRight /></ToggleGroupItem>
+								<ToggleGroupItem aria-label="Bold" value="bold"><Bold /></ToggleGroupItem>
+								<ToggleGroupItem aria-label="Italic" value="italic"><Italic /></ToggleGroupItem>
+								<ToggleGroupItem aria-label="Underline" value="underline"><Underline /></ToggleGroupItem>
+								<ToggleGroupItem aria-label="Align left" value="left"><AlignLeft /></ToggleGroupItem>
+								<ToggleGroupItem aria-label="Align center" value="center"><AlignCenter /></ToggleGroupItem>
+								<ToggleGroupItem aria-label="Align right" value="right"><AlignRight /></ToggleGroupItem>
 							</ToggleGroup>
 		</>
 	);

package/.agents/skills/component-library-rules/references/components/ui__toggles.md

@@ -99,7 +99,7 @@ export function SliderExample() {
 	const [vol, setVol] = useState<number>(40);
 	return (
 		<>
-			<Slider value={[vol]} onValueChange={(v) => setVol(Array.isArray(v) ? v[0] : v)} />
+			<Slider aria-label="Volume" value={[vol]} onValueChange={(v) => setVol(Array.isArray(v) ? v[0] : v)} />
 							<div className="mt-2 text-xs text-muted-foreground">value: {vol}</div>
 		</>
 	);

package/AGENTS.md

@@ -43,7 +43,7 @@ Read it once for context; it is not a live roadmap.
 
 ## Mandatory reading before any code change
 
-The **only** mandatory skill in this repo is
+The **only** mandatory maintainer skill in this repo is
 [`component-library-rules`](.agents/skills/component-library-rules/SKILL.md).
 It encodes 24 rules covering layer order, typography, density, tokens,
 strings/i18n, framework-agnostic contracts, slot/render-prop
@@ -59,9 +59,11 @@ pages, ui-provider, consumer wiring, import paths, visual evaluation,
 testing, layout, composed-domains. Pull the matching one when the work
 fits; don't read all of them.
 
-This skill is **self-sufficient by design** — there are no other skills
-shipped with this repo. If a topic isn't covered, ask before inventing
-a pattern.
+The repo also ships
+[`admin-ui-consumer-migration`](.agents/skills/admin-ui-consumer-migration/SKILL.md)
+for downstream apps migrating copied UI into the package. Use that skill in
+consumer repos; use `component-library-rules` when changing this package.
+If a topic isn't covered, ask before inventing a pattern.
 
 ## The architectural layers
 

package/CHANGELOG.md

@@ -6,6 +6,31 @@ this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.3] — 2026-05-22
+
+### Added
+
+- **Consumer migration playbook** in `MIGRATION.md` for replacing copied local
+  UI trees with direct package imports, including migration order, Inertia
+  wiring, adapter rules, deletion rules, and verification commands.
+- **Component selection guide** in `COMPONENT_SELECTION.md` mapping common admin
+  UI needs to exact package entrypoints.
+- **`admin-ui-consumer-migration` skill** for downstream app migrations. The
+  skill tells agents how to replace copied local UI, avoid local re-export
+  mirrors, keep framework wiring app-owned, and choose exact package imports.
+- **`admin-ui-starter-kit-audit` CLI** to detect stale local copied imports,
+  invalid package subpaths, and local files that only re-export package
+  components. The CLI supports `--fix` for conservative rewrites from known
+  copied paths.
+
+### Changed
+
+- Updated the consumer skill installer and maintainer `publish:skill` workflow
+  to handle multiple shipped skills.
+- Documented the migration flow, audit command, shipped skill files, and exact
+  import rules across `README.md`, `INTEGRATION.md`, `PUBLISHING.md`, and
+  `AGENTS.md`.
+
 ## [0.1.0] — 2026-05-02
 
 Initial public release.
@@ -73,5 +98,6 @@ Initial public release.
 - **What this is not:** a marketing-site UI kit. Built for admin panels
   and SaaS dashboards.
 
-[Unreleased]: https://github.com/nicolasvlachos/admin-ui-starter-kit/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/nicolasvlachos/admin-ui-starter-kit/compare/v0.1.3...HEAD
+[0.1.3]: https://github.com/nicolasvlachos/admin-ui-starter-kit/compare/v0.1.0...v0.1.3
 [0.1.0]: https://github.com/nicolasvlachos/admin-ui-starter-kit/releases/tag/v0.1.0

package/COMPONENT_SELECTION.md

@@ -0,0 +1,115 @@
+# Component Selection Guide
+
+Use this when deciding which package entrypoint belongs at a call site.
+
+Public imports are exact. If a path is not listed in `package.json` `exports`
+or documented here, treat it as private.
+
+## Common decisions
+
+| Need | Use | Import |
+| --- | --- | --- |
+| Text, headings, labels, links | `Text`, `Heading`, `Label`, `TextLink` | `admin-ui-starter-kit/typography` |
+| Button or icon button | `Button`, `TextButton`, button variants | `admin-ui-starter-kit/base/buttons` |
+| Status pill or count badge | `Badge` | `admin-ui-starter-kit/base/badge` |
+| Card shell | `SmartCard` | `admin-ui-starter-kit/base/cards` |
+| Row with icon/avatar/title/meta/actions | `Item` family | `admin-ui-starter-kit/base/item` |
+| Label/value metadata | `MetadataList` | `admin-ui-starter-kit/base/display/metadata` |
+| Tooltip, avatar, separator, inline stat | display family | `admin-ui-starter-kit/base/display` |
+| Form label/control/error row | `FormField`, `ControlledFormField` | `admin-ui-starter-kit/base/forms` |
+| Inputs, selects, textareas, QR fields | form field exports | `admin-ui-starter-kit/base/forms` |
+| Searchable select | `Combobox` | `admin-ui-starter-kit/base/combobox` |
+| Popover menu or command menu | `PopoverMenu`, `Command` | `admin-ui-starter-kit/base/popover-menu`, `admin-ui-starter-kit/base/command` |
+| Dropdown navigation menus | navigation family | `admin-ui-starter-kit/base/navigation` |
+| Data table | `DataTable` | `admin-ui-starter-kit/base/table` |
+| Date picker or date range picker | date picker family | `admin-ui-starter-kit/base/date-pickers` |
+| Map or place autocomplete | map family | `admin-ui-starter-kit/base/map` |
+| KPI cards and charts | analytics surfaces | `admin-ui-starter-kit/composed/analytics` |
+| Commerce/order/product surfaces | commerce surfaces | `admin-ui-starter-kit/composed/commerce` |
+| Timeline | timeline surfaces | `admin-ui-starter-kit/composed/timelines` |
+| Comments panel | `Comments` | `admin-ui-starter-kit/features/comments` |
+| Filter bar/facets | filters feature | `admin-ui-starter-kit/features/filters` |
+| Dialog, drawer, alert dialog | overlays feature | `admin-ui-starter-kit/features/overlays` |
+| Global search shell | global search feature | `admin-ui-starter-kit/features/global-search` |
+| Mentions/typeahead | mentions or suggestions feature | `admin-ui-starter-kit/features/mentions`, `admin-ui-starter-kit/features/suggestions` |
+| Rich text editor | TipTap-backed editor | `admin-ui-starter-kit/features/rich-text-editor` |
+| Page title/actions/breadcrumb chrome | page layout | `admin-ui-starter-kit/layout/page` |
+| Header shell/search/action slots | header layout | `admin-ui-starter-kit/layout/header` |
+| Sidebar shell | sidebar layout | `admin-ui-starter-kit/layout/sidebar` |
+
+## Decision tree
+
+1. Is it plain user-facing text?
+   Use `typography`. Do not hand-roll `text-xs text-muted-foreground` spans.
+
+2. Is it a primitive UI control or presentational wrapper?
+   Use `base`. Buttons, badges, cards, form fields, popovers, tables, maps,
+   display helpers, and item rows live there.
+
+3. Is it a reusable domain-shaped surface built from base components?
+   Use `composed`. Metrics, commerce cards, admin rows, timeline surfaces, and
+   dense data-display blocks belong there.
+
+4. Does it include feature state, slots, callbacks, or app-level behaviour?
+   Use `features`. Comments, filters, search, overlays, mentions, sync, and
+   rich text editor live there.
+
+5. Is it page chrome?
+   Use `layout`. Keep routing and active-link state in the app.
+
+6. Does it hardcode backend, auth, routing, app translations, or product
+   branding?
+   Keep it in the app. Wrap package components only where the wrapper binds
+   app-specific behaviour.
+
+## Adapter examples
+
+Use an app adapter when you bind framework behaviour:
+
+```tsx
+import { router } from '@inertiajs/react';
+import { Button, type ButtonProps } from 'admin-ui-starter-kit/base/buttons';
+
+export function InertiaActionButton({
+	href,
+	method = 'get',
+	...props
+}: ButtonProps & { href: string; method?: 'get' | 'post' | 'put' | 'delete' }) {
+	return <Button {...props} onClick={() => router.visit(href, { method })} />;
+}
+```
+
+Do not create app wrappers that only rename or re-export package components:
+
+```ts
+export { Button } from 'admin-ui-starter-kit/base/buttons';
+```
+
+## Exact import rules
+
+Use:
+
+```tsx
+import { Button } from 'admin-ui-starter-kit/base/buttons';
+import { Text } from 'admin-ui-starter-kit/typography';
+import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
+```
+
+Do not use:
+
+```tsx
+import { Button } from 'admin-ui-starter-kit/base';
+import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata/metadata-list';
+import { Button } from '@/components/ui/base/buttons';
+```
+
+## Where agents should look
+
+1. `AGENTS.md`
+2. `.agents/skills/component-library-rules/SKILL.md`
+3. `.agents/skills/admin-ui-consumer-migration/SKILL.md`
+4. `.agents/skills/component-library-rules/references/components/INDEX.json`
+5. The specific component doc under `references/components/*.md`
+6. `INTEGRATION.md`
+7. `MIGRATION.md`
+8. `package.json` `exports`

package/INTEGRATION.md

@@ -2,6 +2,11 @@
 
 Use this when installing `admin-ui-starter-kit` into a React app.
 
+If the app already has a copied local design system, follow
+[`MIGRATION.md`](MIGRATION.md) first. Use
+[`COMPONENT_SELECTION.md`](COMPONENT_SELECTION.md) when deciding which exact
+entrypoint replaces a local component.
+
 ## 1. Install the package and required peers
 
 ```bash
@@ -15,6 +20,10 @@ Install optional peers only for the entrypoints you import. For example,
 `admin-ui-starter-kit/features/rich-text-editor` needs TipTap,
 `admin-ui-starter-kit/base/table` needs TanStack Table, and
 `admin-ui-starter-kit/base/map` needs the Leaflet peer set.
+`admin-ui-starter-kit/base/date-pickers` needs `react-day-picker@^10`;
+pass-through `calendarProps` follow DayPicker v10, so deprecated v9 props
+such as `fromYear` / `toYear` must be replaced with `startMonth` / `endMonth`.
+The kit-level `yearSelection.fromYear` / `toYear` props remain supported.
 
 ## 2. Import exact entrypoints
 
@@ -140,6 +149,7 @@ For a quick smoke test:
 ```bash
 npm run typecheck
 npm run build
+npx admin-ui-starter-kit-audit
 ```
 
 If a build reports a missing optional peer, either install the peer listed

package/MIGRATION.md

@@ -0,0 +1,239 @@
+# Migration Guide
+
+Use this when replacing a copied local design system with the published
+`admin-ui-starter-kit` package.
+
+The goal is not to move every UI file into npm. The package owns reusable UI.
+The consuming app owns routing, API calls, auth context, translations, brand
+assets, and domain-specific behaviour.
+
+## 1. Install and mount
+
+```bash
+npm install admin-ui-starter-kit react react-dom tailwindcss lucide-react
+```
+
+If the app still uses `lucide-react` v0, upgrade it as part of the migration.
+This package has a lucide v1 peer.
+
+Mount the stylesheet and provider once:
+
+```tsx
+import 'admin-ui-starter-kit/style.css';
+import { UIProvider } from 'admin-ui-starter-kit/ui-provider';
+
+<UIProvider
+	config={{
+		money: { defaultCurrency: 'USD', locale: 'en-US' },
+		dates: { weekStartsOn: 1 },
+		badge: { defaultSize: 'xs' },
+		button: { defaultSize: 'sm' },
+	}}
+>
+	<App />
+</UIProvider>;
+```
+
+## 2. Replace local primitives first
+
+Start with the low-level imports used everywhere. Keep the changes mechanical
+and verify after each group.
+
+```tsx
+import { Button } from 'admin-ui-starter-kit/base/buttons';
+import { Badge } from 'admin-ui-starter-kit/base/badge';
+import { SmartCard } from 'admin-ui-starter-kit/base/cards';
+import { Text, Heading } from 'admin-ui-starter-kit/typography';
+```
+
+Do not create local mirror files that re-export package primitives. Replace the
+call-site imports directly.
+
+## 3. Replace repeated display patterns
+
+Use package components for shapes that repeat across the app:
+
+```tsx
+import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
+import { Item, ItemContent, ItemMedia, ItemTitle } from 'admin-ui-starter-kit/base/item';
+```
+
+Use `MetadataList` for label/value data, compact summaries, and entity details.
+Use `Item` for rows with media, title, description, metadata, or actions.
+
+## 4. Replace form rows
+
+Use the package form shell before moving larger forms:
+
+```tsx
+import { ControlledFormField, Input, Select } from 'admin-ui-starter-kit/base/forms';
+```
+
+Keep form submission, validation schemas, and API mutation wiring in the app.
+The package should own the field row and control presentation, not the backend
+contract.
+
+## 5. Replace tables, filters, metrics, and overlays
+
+Move shared app surfaces after primitives are stable:
+
+```tsx
+import { DataTable } from 'admin-ui-starter-kit/base/table';
+import { FilterProvider } from 'admin-ui-starter-kit/features/filters';
+import { MetricGrid } from 'admin-ui-starter-kit/composed/analytics';
+import { Dialog, Drawer } from 'admin-ui-starter-kit/features/overlays';
+```
+
+Install optional peers only for the entrypoints you import. For example,
+`base/table` needs `@tanstack/react-table`, `composed/analytics` needs
+`recharts`, `features/rich-text-editor` needs TipTap, and
+`base/date-pickers` needs `react-day-picker@^10`. When migrating local date
+picker wrappers, update pass-through DayPicker props to v10 names
+(`startMonth` / `endMonth`) instead of deprecated v9 names
+(`fromYear` / `toYear`).
+
+## 6. Replace layouts last
+
+Migrate page chrome after shared atoms and features are clean:
+
+```tsx
+import { PageHeader, PageActions } from 'admin-ui-starter-kit/layout/page';
+import { Header, HeaderSearch } from 'admin-ui-starter-kit/layout/header';
+import { AppSidebar, SidebarProvider } from 'admin-ui-starter-kit/layout/sidebar';
+```
+
+Route-aware layout state, active navigation logic, auth menus, and application
+search content stay in the app. The package provides the shell and slots.
+
+## 7. Keep app-owned adapters, not local mirrors
+
+A consuming app may create adapters for framework wiring, but not local mirrors.
+
+Good:
+
+```tsx
+import { Link } from '@inertiajs/react';
+import { PageHeader, type PageHeaderProps } from 'admin-ui-starter-kit/layout/page';
+
+export function AppPageHeader(props: PageHeaderProps) {
+	return (
+		<PageHeader
+			{...props}
+			renderLink={(href, children) => <Link href={href}>{children}</Link>}
+		/>
+	);
+}
+```
+
+Bad:
+
+```ts
+export { Button } from 'admin-ui-starter-kit/base/buttons';
+export { Text } from 'admin-ui-starter-kit/typography';
+```
+
+The package owns UI. The app owns routing, API calls, auth context, and
+translations.
+
+## 8. Inertia recipe
+
+Keep Inertia imports in the consuming app:
+
+```tsx
+import { Link, router } from '@inertiajs/react';
+import { Button } from 'admin-ui-starter-kit/base/buttons';
+import { Comments } from 'admin-ui-starter-kit/features/comments';
+import { PageHeader } from 'admin-ui-starter-kit/layout/page';
+
+<PageHeader
+	title="Customers"
+	actions={<Button onClick={() => router.visit('/customers/create')}>Create</Button>}
+	renderLink={(href, children) => <Link href={href}>{children}</Link>}
+/>;
+
+<Comments
+	comments={comments}
+	onSubmit={(values) => router.post(route('comments.store'), values)}
+	onDelete={(id) => router.delete(route('comments.destroy', id))}
+	strings={{
+		empty: t('comments.empty'),
+		composerPlaceholder: t('comments.placeholder'),
+	}}
+/>;
+```
+
+Do not add Inertia adapters to the package. Document app adapters locally when
+they bind routes, Wayfinder actions, translations, or app APIs.
+
+## 9. Do not migrate these
+
+Keep these in the consuming app:
+
+- Brand assets, logos, app icons, and product-specific marks.
+- Error boundaries and app-level exception handling.
+- Route-aware search content and backend-connected global search.
+- Auth menus, permission gates, and tenant/workspace selectors.
+- Domain-specific cards and features that encode business rules.
+- API clients, query caches, Inertia router calls, and Wayfinder route actions.
+- App-specific layout orchestration and page-level data loading.
+
+## 10. Delete copied folders after imports are clean
+
+Only delete local copied folders after typecheck and build pass:
+
+```text
+components/ui/base
+components/ui/typography
+components/ui/navigation
+components/layout
+components/features/comments
+components/features/filters
+components/features/metrics
+```
+
+The exact folders vary by app. Delete only copied package equivalents; keep
+app-owned components.
+
+## 11. Hard import rules
+
+Use exact public exports:
+
+```tsx
+import { Button } from 'admin-ui-starter-kit/base/buttons';
+import { Text } from 'admin-ui-starter-kit/typography';
+import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
+```
+
+Do not use:
+
+```tsx
+import { Button } from '@/components/ui/base/buttons';
+import { Button } from 'admin-ui-starter-kit/base';
+import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata/metadata-list';
+```
+
+Run the package audit in a consumer app:
+
+```bash
+npx admin-ui-starter-kit-audit
+```
+
+Use `--fix` for conservative import rewrites from known copied paths:
+
+```bash
+npx admin-ui-starter-kit-audit --fix
+```
+
+## 12. Verification
+
+After each migration chunk:
+
+```bash
+npm run typecheck
+npm run build
+npx admin-ui-starter-kit-audit
+```
+
+If a package import fails, check `package.json` `exports` in
+`admin-ui-starter-kit`. Public imports are exact keys. Undocumented nested
+paths are private even when declaration files exist under `dist/`.

package/PUBLISHING.md

@@ -54,7 +54,12 @@ Read the file list. **Confirm:**
 - `dist/files/` and `dist/images/` are included for font and map CSS assets.
 - `style.css.d.ts` is included for strict TypeScript side-effect CSS imports.
 - `dist/showcase/` is included.
-- `README.md`, `INTEGRATION.md`, `LICENSE`, `CHANGELOG.md` are included.
+- `README.md`, `INTEGRATION.md`, `MIGRATION.md`,
+  `COMPONENT_SELECTION.md`, `LICENSE`, `CHANGELOG.md` are included.
+- `.agents/skills/component-library-rules/` and
+  `.agents/skills/admin-ui-consumer-migration/` are included.
+- `scripts/audit-consumer.mjs`, `scripts/install-skill.mjs`, and
+  `scripts/serve-showcase.mjs` are included.
 - `src/App.css` is included so consumers can copy the token source when
   building their own Tailwind output.
 - `node_modules/`, `coverage/`, `.git/`, `dist-ssr/`, the preview app

package/README.md

@@ -99,6 +99,11 @@ exactly your tool.**
 For a full framework and bundler setup walkthrough, see
 [INTEGRATION.md](INTEGRATION.md).
 
+Migrating an app that already copied an older local UI tree? Start with
+[MIGRATION.md](MIGRATION.md), then use
+[COMPONENT_SELECTION.md](COMPONENT_SELECTION.md) to choose exact package
+entrypoints.
+
 ### 1. Add the package
 
 ```bash
@@ -125,14 +130,18 @@ plan that icon-package upgrade as part of adoption.
 | `base/table` | `@tanstack/react-table` |
 | `composed/analytics` (charts) | `recharts` |
 | `composed/cards` with sortable lists | `@dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities` |
-| `base/date-pickers` | `react-day-picker` |
+| `base/date-pickers` | `react-day-picker@^10` |
 | `base/forms/fields/qr-code` | `qrcode` |
 | `base/forms` (the `ControlledFormField`) | `react-hook-form` |
 | `base/toaster` | `sonner` |
 | `base/command` | `cmdk` |
 | `base/currency` (color tools) | `culori` |
 
-Skip the ones you don't import — npm will warn but not fail.
+Skip the ones you don't import — npm will warn but not fail. Date picker
+`calendarProps` are forwarded to DayPicker v10, so use v10 prop names
+(`startMonth` / `endMonth`) rather than deprecated v9 names. The kit-level
+`yearSelection.fromYear` / `toYear` option remains supported and is mapped
+internally.
 
 ### 4. Mount the stylesheet
 
@@ -164,23 +173,37 @@ import { UIProvider } from 'admin-ui-starter-kit/ui-provider';
 
 The provider is locked at first mount; pass everything once at the root.
 
-### 6. Install the AI agent skill (optional)
+### 6. Install the AI agent skills (optional)
+
+This package ships AI skills for Claude Code and other agents:
 
-This package ships a `component-library-rules` skill for Claude Code and other
-AI agents. After installing the package:
+- `component-library-rules` — maintainer rules for editing this library.
+- `admin-ui-consumer-migration` — consumer-app migration rules and guardrails.
+
+After installing the package:
 
 ```bash
 npx admin-ui-starter-kit-install-skill
 ```
 
-Copies the skill into your project's `.claude/skills/component-library-rules/`
-and `.agents/skills/component-library-rules/`. Run again to update after a
-package upgrade.
+Copies both skills into your project's `.claude/skills/` and
+`.agents/skills/`. Run again to update after a package upgrade.
 
 Flags:
+- `--skill=all|component-library-rules|admin-ui-consumer-migration` (default `all`)
 - `--target=claude|agents|both` (default `both`) — pick which directory to install into.
 - `--force` — overwrite without prompting.
 
+For migration checks in a consuming app:
+
+```bash
+npx admin-ui-starter-kit-audit
+npx admin-ui-starter-kit-audit --fix
+```
+
+The audit rejects stale copied imports, invalid package subpaths, and local
+files that only re-export package components.
+
 ---
 
 ## Browse the component showcase