admin-ui-starter-kit 0.4.5 → 0.6.1

package/.agents/skills/token-system/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: token-system
+description: "Use when auditing, modifying, documenting, or explaining the admin-ui-starter-kit token system: shadcn theme variables, src/css/themes/shadcn.default.css, src/css/tokens/*, compatibility aggregators, Tailwind v4 @theme/@utility aliases, CSS variable docs, density/spacing/typography/control tokens, or consumer override/publish-theme workflows."
+---
+
+# Token System
+
+This skill is for the package token contract, not ordinary component styling.
+Use it before editing `src/App.css`, `src/css/themes/shadcn.default.css`,
+`src/css/tokens/*`, compatibility aggregators, token docs, token checks, or
+consumer guidance.
+
+## Ownership
+
+- `src/App.css` is the Tailwind/import entrypoint.
+- `src/css/themes/shadcn.default.css` owns only shadcn-compatible color,
+  radius, shadow, dark/light, chart, and sidebar tokens.
+- `src/css/tokens/foundation.css` owns fonts, typography scale, spacing scale,
+  and density primitives.
+- `src/css/tokens/states.css` owns package state extensions such as success,
+  info, warning, and inverse surfaces.
+- `src/css/tokens/primitives.css` owns package radius aliases, action/control
+  heights, control spacing, and media sizes.
+- `src/css/tokens/layout.css` owns shell/header/sidebar dimensions.
+- `src/css/tokens/components.css` owns row, surface, and narrow component knobs.
+- `src/css/tokens/compat.css` owns temporary deprecated aliases only.
+- `src/css/themes/default.css` and `src/css/defaults.css` are legacy
+  aggregators for source-level compatibility, not the primary ownership files.
+- `<UIProvider>` owns JS-side display defaults only: locale-ish formatting,
+  default component sizes, default table density, and similar runtime choices.
+
+## Workflow
+
+1. Read the relevant CSS file and `scripts/check-token-contract.mjs`.
+2. Read `src/preview/pages/base/css-variables.mdx` when documentation or
+   consumer-facing behavior is involved.
+3. Keep the public structural root contract compact. Add a root variable only
+   when a real cross-component responsibility cannot be expressed through an
+   existing structural token.
+4. Use Tailwind aliases from structural tokens in components: `h-control`,
+   `px-control`, `gap-space-*`, `py-row-y`, `px-surface`, `size-icon`, and
+   `size-avatar`.
+5. Do not create component-family token aliases for action controls, cards,
+   tables, headers, app shells, or text roles.
+6. Run `npm run lint:tokens` after token docs, classes, aliases, or CSS change.
+
+## Shadcn Boundary
+
+Shadcn primitives expect the theme token names from `themes/shadcn.default.css`
+(`--background`, `--foreground`, `--card`, `--popover`, `--border`, `--input`,
+`--ring`, `--primary`, `--secondary`, `--muted`, `--accent`,
+`--destructive`, radius, shadows, sidebar). Keep those names stable.
+
+Do not move shadcn palette/radius/shadow values into package token files. Do
+not put success/info/warning, spacing, density, action/control height, row
+padding, layout, component knobs, or media size into the shadcn theme file.
+
+## Consumer Overrides
+
+For normal consumers, prefer:
+
+```tsx
+import 'admin-ui-starter-kit/style.css';
+```
+
+Then override public variables in app CSS. For editable local copies, use:
+
+```bash
+npx admin-ui-starter-kit-publish-theme
+```
+
+That command publishes editable `theme.css` and a flattened `defaults.css`
+containing package-owned token layers into the consumer app. See
+`references/consumer-overrides.md` for the decision tree.
+
+## Checks
+
+- `npm run lint:tokens` for contract and removed utility use.
+- `npm run docs:sync-skill -- --check` after token docs change.
+- `npm run build:showcase` when MDX token docs or examples change.
+- `npm run test:package-smoke:check` after package file/bin changes.

package/.agents/skills/token-system/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Admin UI Token System"
+  short_description: "Work with admin-ui structural and shadcn tokens"
+  default_prompt: "Use $token-system to audit, modify, or explain the admin-ui-starter-kit token contract, shadcn theme adapter, package token layers, Tailwind aliases, and consumer override workflow."

package/.agents/skills/token-system/references/consumer-overrides.md

@@ -0,0 +1,68 @@
+# Consumer Token Override Decision Tree
+
+Use this when a consuming app wants to customize the admin-ui-starter-kit
+visual system.
+
+## Default Mode
+
+Use the compiled package stylesheet:
+
+```tsx
+import 'admin-ui-starter-kit/style.css';
+```
+
+Then add a local CSS file after it for runtime variable overrides:
+
+```css
+:root {
+	--space-scale: 0.95;
+	--density-scale: 0.95;
+	--shell-sidebar-width: 17rem;
+}
+```
+
+This is the safest mode. It keeps package utilities, feature-local CSS,
+animations, and shadcn mappings intact.
+
+## Published Theme Mode
+
+Run:
+
+```bash
+npx admin-ui-starter-kit-publish-theme
+```
+
+The command writes editable `theme.css`, `defaults.css`, and a local
+`admin-ui.css` entrypoint. Use this when the consumer needs a checked-in theme
+file instead of a tiny override file.
+
+Keep the split:
+
+- `theme.css`: shadcn-compatible color, radius, shadows, charts, sidebar, and
+  dark/light values.
+- `defaults.css`: flattened package token layers for text scale, spacing scale,
+  density, states, action/control heights, rows, surfaces, icon/avatar sizes,
+  shell dimensions, component knobs, compatibility aliases, and Tailwind
+  aliases.
+
+## Tailwind Source Mode
+
+Use only when the consumer intentionally rebuilds Tailwind from source rather
+than importing the package `style.css`.
+
+Requirements:
+
+- Include `admin-ui-starter-kit/dist/**/*.{js,cjs}` in Tailwind content or
+  `@source`.
+- Import local `theme.css` and `defaults.css` from the app CSS entrypoint.
+- Keep feature-local CSS coverage. The compiled package stylesheet already has
+  it; custom source mode must account for package feature styles separately if
+  they are needed.
+
+## Do Not
+
+- Do not copy old action/card/table/header/app-shell token families forward.
+- Do not override structure by scattering arbitrary `text-[...]`, `px-[...]`,
+  `gap-[...]`, or `size-[...]` values through app JSX.
+- Do not edit package files under `node_modules`; publish local copies or
+  override variables in app-owned CSS.

package/AGENTS.md

@@ -25,9 +25,12 @@ The architectural goals — and the reason every rule below exists — are:
 3. **Composable**: every complex feature exposes slots, render-props, and
    headless hooks so consumers can reshape any portion without forking.
 4. **Theme-able**: shadcn tokens are the foundation; on top, the library
-   exposes typography (`--text-xs`, …), density (`--row-py-*`), and
-   component-specific CSS variables in `App.css` so consumers rebrand
-   from `:root` without touching JS. App-wide JS-side display defaults
+   exposes a compact structural token contract in standalone files under
+   `src/css/tokens/` (`--text-scale`, `--space-scale`, `--density-scale`,
+   `--space-*`, `--rounded-radius*`, `--height-action*`,
+   `--height-control*`, `--control-*`, `--row-*`, `--surface-*`,
+   `--icon*`, `--avatar*`, and shell dimensions) so consumers tune scale
+   from `:root` or a scoped wrapper without touching JS. App-wide JS-side display defaults
    (default currency, week-start, default badge size, …) live in a
    single zustand store wrapped by `<UIProvider>` (see
    `@/lib/ui-provider`). One provider, no nesting.
@@ -136,8 +139,14 @@ Hard rules (full detail in the skill):
   callbacks, data, and resource registries are **always** direct props
   on the actual component — never put them in the store. Canonical
   slice list: see the union types in `src/lib/ui-provider/types.ts`.
-- **Tokens**: `src/App.css` — typography, density, semantic colours,
-  shadcn token composition. Read the comment blocks before editing.
+- **Tokens**: `src/App.css` imports the token layers. Shadcn palette,
+  radius, shadow, dark/light, chart, and sidebar tokens live in the swappable
+  `src/css/themes/shadcn.default.css` adapter. Package-owned states,
+  structural typography scale, spacing, density, action/control heights, rows,
+  surfaces, media sizing, shell dimensions, component knobs, and compatibility
+  aliases live in standalone files under `src/css/tokens/`. The legacy
+  `src/css/themes/default.css` and `src/css/defaults.css` files are
+  compatibility aggregators only. Read those comment blocks before editing.
 - **Strings pattern**: every component with user-facing text exports a
   `*Strings` interface + `default*Strings` defaults; the prop is
   deep-merged via `useStrings(defaults, override)`. See
@@ -204,10 +213,22 @@ For the visual pass:
 
 ```
 src/
-├── App.css                       — design tokens (colors, typography
-│                                   font-size vars, density tokens,
-│                                   per-component knobs). Read the
-│                                   comment blocks before editing.
+├── App.css                       — CSS entrypoint that imports default
+│                                   structural tokens plus theme tokens.
+├── css/
+│   ├── defaults.css              — legacy aggregator for token layers.
+│   ├── themes/
+│   │   ├── default.css           — legacy aggregator for shadcn.default.css.
+│   │   └── shadcn.default.css    — swappable shadcn palette, radius, shadows,
+│   │                               charts, sidebar, dark/light.
+│   └── tokens/
+│       ├── foundation.css        — fonts, typography, spacing, density.
+│       ├── states.css            — success/info/warning/inverse tokens.
+│       ├── primitives.css        — radius aliases, action/control heights,
+│       │                           control/media sizing.
+│       ├── layout.css            — shell/header/sidebar dimensions.
+│       ├── components.css        — row/surface/component knobs.
+│       └── compat.css            — temporary deprecated aliases.
 ├── components/
 │   ├── ui/                       — shadcn primitives. Read-only.
 │   ├── typography/               — Text, Heading, Label, TextLink
@@ -330,9 +351,11 @@ When in doubt, model new work on these reference implementations:
   "label + control + hint/helper/error" row. Pure presentational
   (`<FormField>`) and react-hook-form-bound (`<ControlledFormField>`)
   variants both live there.
-- **Token-driven typography & density** → `App.css` `@theme` block.
-  Component CSS reads `var(--text-xs)` / `var(--row-py)` etc., never
-  hardcoded literals.
+- **Token-driven typography & density** → `src/css/tokens/foundation.css` and
+  `src/css/tokens/primitives.css`.
+  Component CSS and Tailwind utilities route through `--text-*`,
+  `--space-*`, `--control-*`, `--row-*`, `--surface-*`, `--icon*`,
+  and `--avatar*`; do not reintroduce component-family token aliases.
 
 ## Do NOT touch
 
@@ -420,11 +443,13 @@ When in doubt, model new work on these reference implementations:
   (`useGlobalSearch`, `useFilters`, `useAsyncOptions`).
 - **Strings prop** — every user-facing string in a component is
   reachable via `strings={{ … }}`, deep-merged over `default*Strings`.
-- **Density token** — `--row-py-tight | --row-py-default |
-  --row-py-loose`. Consumed by list rows; consumer can override at
-  any wrapping element to densify a single surface.
-- **Token-driven typography** — `--text-xxs/xs/sm/base/lg`. Consumer
-  can override at `:root` to resize the entire library.
+- **Density token** — `--density-scale` plus row/control variables such as
+  `--row-y-sm`, `--row-y`, `--row-y-lg`, `--control-height-sm`, and
+  `--control-height`. Consumers can override them at `:root` or on a scoped
+  wrapper to densify a surface.
+- **Token-driven typography** — Tailwind text utilities resolve through
+  `--text-scale` and the `--text-xxs/xs/sm/base/lg/xl/2xl` scale. Consumers
+  override `--text-scale` first, then individual text tokens only when needed.
 
 ## Commit / PR conventions
 

package/CHANGELOG.md

@@ -6,7 +6,7 @@ this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
-## [0.4.5] — 2026-06-20
+## [0.4.6] — 2026-06-20
 
 ### Added
 
@@ -23,6 +23,13 @@ this project adheres to [Semantic Versioning](https://semver.org/).
 - **Dependency-free action adapters** — added HTTP, Inertia-like, and React
   Query-like helpers that accept router/query-client objects without importing
   framework packages into the library.
+- **Neutral action runtime glue** — added `ActionRuntimeGlue` and neutral
+  `ActionRequestTarget` request definitions. `ActionProvider` now accepts
+  `runtime` while keeping direct props as overriding compatibility props.
+- **Admin pattern primitives** — added header tool primitives, admin shell
+  aliases, resource page shells/cards, form workflow chrome, and data-view
+  toolbar/pagination/saved-view primitives so consumers can reuse package
+  patterns instead of rebuilding page glue.
 
 ### Fixed
 
@@ -40,6 +47,15 @@ this project adheres to [Semantic Versioning](https://semver.org/).
   the service README, and the consumer migration skill with provider contracts,
   request runners, guards, error parsing, local actions, and migration choice
   points.
+- Added neutral consumer glue recipes for routing, transport, cache
+  invalidation, toasts, permissions, backend error parsing, polling pause, and
+  busy state. Framework-named action helpers remain available in `0.4.x` but
+  are deprecated in favor of consumer-owned `ActionRuntimeGlue`.
+
+### Maintenance
+
+- Strengthened `lint:architecture` so package source cannot import framework
+  runtimes and new framework-named action exports are rejected.
 
 ## [0.1.3] — 2026-05-22
 
@@ -133,7 +149,7 @@ 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.4.5...HEAD
-[0.4.5]: https://github.com/nicolasvlachos/admin-ui-starter-kit/compare/v0.1.3...v0.4.5
+[Unreleased]: https://github.com/nicolasvlachos/admin-ui-starter-kit/compare/v0.4.6...HEAD
+[0.4.6]: https://github.com/nicolasvlachos/admin-ui-starter-kit/compare/v0.1.3...v0.4.6
 [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

@@ -13,26 +13,31 @@ or documented here, treat it as private.
 | 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` |
-| Section frame or grouped panels | `Frame` family | `admin-ui-starter-kit/base/frame` |
+| Section card or grouped panels | `SmartCard` | `admin-ui-starter-kit/base/cards` |
+| Page section/container layout | `Container`, `Section` | `admin-ui-starter-kit/layout/containers` |
 | 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` |
+| Label/value metadata | `MetadataList` | `admin-ui-starter-kit/composed/data-display` |
 | Alert, tooltip, avatar, separator, inline stat | display family | `admin-ui-starter-kit/base/display` |
 | Recharts primitives with themed tooltip/legend | chart display family | `admin-ui-starter-kit/base/display/chart` |
 | Form label/control/error row | `FormField`, `ControlledFormField` | `admin-ui-starter-kit/base/forms` |
 | Inputs, password reveal, selects, textareas, QR fields | form field exports | `admin-ui-starter-kit/base/forms` |
+| Form sections, dirty/error/submit state | `FormSection`, `FormActionsBar`, `ErrorSummary`, `DirtyStateBanner`, `SubmitStateButton` | `admin-ui-starter-kit/base/forms` |
 | Backend/schema-driven settings forms | `SchemaForm`, `useSchemaForm` | `admin-ui-starter-kit/features/schema-form` |
-| Searchable select | `EnhancedCombobox`, `EnhancedComboboxMultiple` | `admin-ui-starter-kit/base/combobox` |
+| Searchable select / async resource picker | `EnhancedCombobox`, `EnhancedComboboxMultiple`, `AsyncResourceCombobox` | `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` |
 | Embla-backed carousel controls | `Carousel` family | `admin-ui-starter-kit/base/carousel` |
 | Dropdown navigation menus | navigation family | `admin-ui-starter-kit/base/navigation` |
-| Data table | `DataTable` | `admin-ui-starter-kit/base/table` |
+| Data table / index table cells | `DataTable`, `ResourceCell`, `StatusClusterCell`, `DateMetaCell` | `admin-ui-starter-kit/base/table` |
+| Data view toolbar/pagination/saved views | `DataViewShell`, `DataViewToolbar`, `DataViewPagination`, `SavedViewTabs` | `admin-ui-starter-kit/features/data-view` |
 | 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 chart cards | analytics surfaces | `admin-ui-starter-kit/composed/analytics` |
+| Selected resource card | `ResourceSelectorCard` | `admin-ui-starter-kit/composed/data-display` |
+| Settings/security action rows and token manager | `ActionList`, `ActionRow`, `SensitiveActionCard`, `CopyableSecretAlert`, `ApiTokenManager` | `admin-ui-starter-kit/composed/admin` |
 | 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` |
+| Filter bar/facets/query helpers | filters feature, `parseFiltersFromQuery`, `serializeFiltersToQuery`, `mergeFilterQuery` | `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` |
 | Media picker, asset library, product gallery field | `MediaLibrary`, `MediaLibraryDialog`, `useMediaLibrary` | `admin-ui-starter-kit/features/media-library` |
@@ -40,6 +45,8 @@ or documented here, treat it as private.
 | Rich text editor | TipTap-backed editor | `admin-ui-starter-kit/features/rich-text-editor` |
 | Auth card or split-page chrome | `AuthShell`, `AuthCard`, `AuthSplitPanel`, social/policy/language slots | `admin-ui-starter-kit/layout/auth` |
 | Page title/actions/breadcrumb chrome | page layout | `admin-ui-starter-kit/layout/page` |
+| Resource index/show page chrome | resource layout | `admin-ui-starter-kit/features/resource` |
+| Settings/aside navigation page chrome | `SettingsShell`, `AsideNavShell` | `admin-ui-starter-kit/layout/settings` |
 | Header shell/search/action slots | header layout | `admin-ui-starter-kit/layout/header` |
 | Sidebar shell | sidebar layout | `admin-ui-starter-kit/layout/sidebar` |
 | Shared action lifecycle across page/table/card/command/overlay surfaces | actions service | `admin-ui-starter-kit/services/actions` |
@@ -58,8 +65,8 @@ or documented here, treat it as private.
    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.
+   Use `features`. Comments, filters, data-view chrome, search, overlays,
+   mentions, sync, and rich text editor live there.
 
 5. Is it page chrome?
    Use `layout`. Keep routing, active-link state, auth requests, and app
@@ -112,10 +119,40 @@ uploading, metadata updates, routing, and storage through props such as
 `fetcher`, `onUpload`, `onItemUpdate`, `onItemDelete`, `value`, and
 `onValueChange`.
 
+Use `AsyncResourceCombobox` when a selector fetches remote resources by search
+query. The package owns debounce, loading, empty, error, abort, clear, and
+keyboard behavior; the app supplies `fetcher`, accessors, translations, and
+error telemetry.
+
+Use `ResourceSelectorCard` for a selected resource inside forms, dialogs, or
+show pages. The app owns the picker overlay and routing; the card only renders
+the selected resource through accessors and calls `onSelect` / `onRemove`.
+
+Use `DataTable` selection toolbar props plus `ResourceCell`,
+`StatusClusterCell`, and `DateMetaCell` for dense index pages. Keep URL state,
+sorting persistence, row navigation, and data fetching in the app.
+
+Use `parseFiltersFromQuery`, `serializeFiltersToQuery`, and `mergeFilterQuery`
+to bridge filters with URL search params. They return plain query records and
+never navigate.
+
+Use `SettingsShell` / `AsideNavShell` for settings pages with a left nav and
+content slot. Pass `renderLink` for framework-native links; keep permissions
+and route generation in the app.
+
 Typography is not optional glue. Use `Text`, `Heading`, `Label`, and `TextLink`
 from `admin-ui-starter-kit/typography` instead of raw font-size, weight, or
 muted-color utility classes.
 
+Tokenization is also part of component selection. If local code exists mainly
+to standardize height, padding, icon size, row spacing, card spacing, or table
+density, prefer the package component that already consumes structural tokens.
+Tune product-wide shape through `--text-scale`, `--space-scale`,
+`--density-scale`, `--control-*`, `--row-*`, `--surface-*`, `--space-*`,
+`--icon*`, and `--avatar*`. Do not select or keep copied components just to
+preserve old component-family aliases for action controls, cards, tables,
+headers, app shells, or component-specific text roles.
+
 ## Adapter examples
 
 Use an app adapter when you bind framework behaviour:
@@ -147,14 +184,14 @@ Use:
 import { Button } from 'admin-ui-starter-kit/base/buttons';
 import { Text } from 'admin-ui-starter-kit/typography';
 import { ChartContainer } from 'admin-ui-starter-kit/base/display/chart';
-import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
+import { MetadataList } from 'admin-ui-starter-kit/composed/data-display';
 ```
 
 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 { MetadataList } from 'admin-ui-starter-kit/composed/data-display/metadata-list';
 import { Button } from '@/components/ui/base/buttons';
 ```
 

package/INTEGRATION.md

@@ -37,18 +37,24 @@ import { UIProvider } from 'admin-ui-starter-kit/ui-provider';
 import { Text } from 'admin-ui-starter-kit/typography';
 import { Button } from 'admin-ui-starter-kit/base/buttons';
 import { Carousel } from 'admin-ui-starter-kit/base/carousel';
-import { EnhancedCombobox } from 'admin-ui-starter-kit/base/combobox';
+import { AsyncResourceCombobox, EnhancedCombobox } from 'admin-ui-starter-kit/base/combobox';
+import { DataTable, ResourceCell } from 'admin-ui-starter-kit/base/table';
 import { ControlledFormField, Input, PasswordInput } from 'admin-ui-starter-kit/base/forms';
-import { Frame } from 'admin-ui-starter-kit/base/frame';
+import { SmartCard } from 'admin-ui-starter-kit/base/cards';
 import { Item, ItemContent, ItemMedia, ItemTitle } from 'admin-ui-starter-kit/base/item';
 import { ChartContainer } from 'admin-ui-starter-kit/base/display/chart';
-import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
+import { MetadataList } from 'admin-ui-starter-kit/composed/data-display';
 import { ChartCard } from 'admin-ui-starter-kit/composed/analytics';
+import { ActionList, ApiTokenManager } from 'admin-ui-starter-kit/composed/admin';
+import { ResourceSelectorCard } from 'admin-ui-starter-kit/composed/data-display';
 import { Comments } from 'admin-ui-starter-kit/features/comments';
+import { mergeFilterQuery, parseFiltersFromQuery, serializeFiltersToQuery } from 'admin-ui-starter-kit/features/filters';
 import { MediaLibraryDialog } from 'admin-ui-starter-kit/features/media-library';
 import { SchemaForm } from 'admin-ui-starter-kit/features/schema-form';
 import { AuthShell } from 'admin-ui-starter-kit/layout/auth';
 import { PageHeader } from 'admin-ui-starter-kit/layout/page';
+import { ResourceIndexShell, ResourceShowShell } from 'admin-ui-starter-kit/features/resource';
+import { SettingsShell } from 'admin-ui-starter-kit/layout/settings';
 import { ActionProvider, ActionOverlayOutlet } from 'admin-ui-starter-kit/services/actions';
 ```
 
@@ -59,7 +65,7 @@ they would force optional peers into apps that do not use them.
 
 Only documented nested subfamily entrypoints are public. For example,
 `MetadataList` is intentionally exported from
-`admin-ui-starter-kit/base/display/metadata`, and chart primitives are exported
+`admin-ui-starter-kit/composed/data-display`, and chart primitives are exported
 from `admin-ui-starter-kit/base/display/chart`, so consumers can avoid optional
 peers they do not use.
 
@@ -85,6 +91,23 @@ Common primitive choices:
 - Use `EnhancedCombobox` / `EnhancedComboboxMultiple` for searchable selects;
   wrap them in `ControlledFormField` inside forms and pass `invalid={invalid}`
   from the render-prop.
+- Use `AsyncResourceCombobox` for remote resource selectors. The component owns
+  debounce, abort, loading, empty, clear, keyboard, and error-display state;
+  the app supplies `fetcher`, accessors, strings, and `onError`.
+- Use `DataTable` with `ResourceCell`, `StatusClusterCell`, and `DateMetaCell`
+  for index pages. The package owns table ergonomics and selected-row chrome;
+  the app owns sorting/query persistence, data fetching, row routing, and
+  backend state.
+- Use `parseFiltersFromQuery`, `serializeFiltersToQuery`, and
+  `mergeFilterQuery` to synchronize filters with URL search params. They
+  return plain records; the consuming app decides how to navigate.
+- Use `ResourceIndexShell`, `ResourceShowShell`, `TabbedResourceShell`, and
+  `SettingsShell` for page chrome. Pass `renderLink` for framework-native
+  links and keep route generation/permissions in the app.
+- Use `ResourceSelectorCard`, `ActionList`, `SensitiveActionCard`, and
+  `ApiTokenManager` for selected-resource, settings, security, and token
+  management surfaces. Persistence and confirmation behavior stay callback
+  driven.
 - Use `SchemaForm` from `admin-ui-starter-kit/features/schema-form` when the
   app already has backend-provided field definitions, tenant settings, or
   integration configuration that should render as a cohesive form or section
@@ -135,6 +158,47 @@ Strict TypeScript apps can import the CSS file directly; the package ships
 `style.css.d.ts` for that side-effect import. The CSS asset files referenced
 by the compiled stylesheet are shipped in `dist/files/` and `dist/images/`.
 
+### Structural token contract
+
+The compiled stylesheet already includes the shadcn adapter and package token
+layers. Keep the split clear when overriding them:
+
+- `src/css/themes/shadcn.default.css` owns shadcn-compatible color, radius,
+  shadow, dark/light, chart, and sidebar variables.
+- `src/css/tokens/*` owns package-specific typography scale, spacing, density,
+  states, action/control heights, row rhythm, surface padding, media sizing,
+  shell dimensions, component knobs, and temporary compatibility aliases.
+
+For product-wide scale changes, override `--text-scale`, `--space-scale`, and
+`--density-scale` first. Use public structural variables such as
+`--control-height`, `--control-x`, `--row-y`, `--surface-x`, `--icon`,
+`--avatar`, and `--shell-sidebar-width` only when the scale knobs are too broad.
+Use the package utilities (`h-control`, `px-control`, `gap-space-md`,
+`py-row-y`, `px-surface`, `size-icon`, `size-avatar`) instead of arbitrary
+`text-[...]`, `gap-[...]`, `px-[...]`, or `size-[...]` values for ordinary
+admin UI.
+
+Do not keep or recreate component-family token aliases in a consuming app for
+action controls, cards, tables, headers, app shells, or component-specific text
+roles. If a local copied component depends on those names, migrate it to the
+package component or map it to the structural token that reflects its
+responsibility.
+
+When a consumer wants checked-in editable token files, publish them from the
+installed package:
+
+```bash
+npx admin-ui-starter-kit-publish-theme
+```
+
+The command writes `src/styles/admin-ui/theme.css`, `defaults.css`,
+`overrides.css`, `admin-ui.css`, and `source.css`. `theme.css` is the swappable
+shadcn adapter; `defaults.css` is a flattened editable copy of the package
+token layers. Import
+`src/styles/admin-ui/admin-ui.css` for package CSS plus local variable
+overrides. Use `source.css` only when the app intentionally rebuilds Tailwind
+instead of importing `admin-ui-starter-kit/style.css`.
+
 ## 4. Wire frameworks at the call site
 
 The library never imports routing, query, backend, or i18n integrations.
@@ -164,9 +228,9 @@ import {
 	ActionOverlayOutlet,
 	ActionProvider,
 	ActionScope,
-	createInertiaActionRunner,
-	createReactQueryActionFeedback,
 	type ActionDefinition,
+	type ActionRequestRunner,
+	type ActionRuntimeGlue,
 } from 'admin-ui-starter-kit/services/actions';
 
 const customerActions: ActionDefinition<Customer>[] = [
@@ -195,32 +259,58 @@ const customerActions: ActionDefinition<Customer>[] = [
 		},
 		request: {
 			method: 'post',
-			route: 'customers.archive',
-			params: ({ payload }) => payload?.id,
+			target: ({ payload }) => ({
+				type: 'named',
+				name: 'customers.archive',
+				params: payload?.id,
+			}),
 			options: { preserveScroll: true },
 		},
 		successMessage: ({ payload }) => `${payload?.name} archived`,
 	},
 ];
 
-<ActionProvider
-	requestRunner={createInertiaActionRunner({ router, route })}
-	feedback={createReactQueryActionFeedback({
-		queryClient,
-		invalidate: (event) => ({ queryKey: [event.actionId] }),
-		feedback: {
-			onSuccess: (event) => event.message && toast.success(event.message),
-			onError: (event) => event.message && toast.error(event.message),
+const requestRunner: ActionRequestRunner = async (request) => {
+	if (request.target?.type === 'named') {
+		return appVisit(appRoute(request.target.name, request.target.params), {
+			...request.options,
+			method: request.method,
+			data: request.data,
+			headers: request.headers,
+		});
+	}
+
+	if (request.target?.type === 'url') {
+		return appHttp(request.target.url, {
+			...request.options,
+			method: request.method,
+			data: request.data,
+			headers: request.headers,
+		});
+	}
+
+	throw new Error('Action request target is missing.');
+};
+
+const actionRuntime: ActionRuntimeGlue = {
+	requestRunner,
+	feedback: {
+		onSuccess: (event) => {
+			if (event.message) toast.success(event.message);
+			queryClient.invalidateQueries({ queryKey: [event.actionId] });
 		},
-	})}
-	guards={{
+		onError: (event) => event.message && toast.error(event.message),
+	},
+	guards: {
 		can: (permission) => auth.can(permission),
 		hasAnyRole: (roles) => auth.hasAnyRole(roles),
-	}}
-	parseErrors={(error) => parseLaravelActionError(error)}
-	onOverlayOpenChange={(open) => polling.setPaused(open)}
-	onRunningChange={(running) => activity.setBusy(running)}
->
+	},
+	parseErrors: (error) => parseBackendActionError(error),
+	onOverlayOpenChange: (open) => polling.setPaused(open),
+	onRunningChange: (running) => activity.setBusy(running),
+};
+
+<ActionProvider runtime={actionRuntime}>
 	<ActionScope scope={`customer:${customer.id}`} actions={customerActions}>
 		<CustomerPage />
 	</ActionScope>

package/MIGRATION.md

@@ -34,6 +34,35 @@ import { UIProvider } from 'admin-ui-starter-kit/ui-provider';
 </UIProvider>;
 ```
 
+The stylesheet is part of the package contract, not a theme afterthought. When
+the consuming app already has copied CSS variables, replace local
+component-family aliases with the package structural tokens:
+
+- Theme/color overrides go to shadcn-compatible variables from
+  `src/css/themes/default.css`.
+- Structure overrides go to the compact contract from `src/css/defaults.css`:
+  `--text-scale`, `--space-scale`, `--density-scale`, `--space-*`,
+  `--control-*`, `--row-*`, `--surface-*`, `--icon*`, `--avatar*`, and shell
+  dimensions.
+- Remove local component-family aliases for action controls, cards, tables,
+  headers, app shells, and component-specific text roles instead of carrying
+  them forward.
+
+Use component APIs and `<UIProvider>` defaults for normal sizing choices. Use
+root structural variables only when the product needs a global or scoped scale
+change.
+
+If the app needs checked-in editable token files, publish them from the
+installed package:
+
+```bash
+npx admin-ui-starter-kit-publish-theme
+```
+
+Import the generated `src/styles/admin-ui/admin-ui.css` instead of importing
+`admin-ui-starter-kit/style.css` directly. It still pulls in the package CSS,
+then applies local token overrides.
+
 ## 2. Replace local primitives first
 
 Start with the low-level imports used everywhere. Keep the changes mechanical
@@ -62,6 +91,9 @@ Use `MetadataList` for label/value data, compact summaries, and entity details.
 Use `Item` for rows with their own identity, media, title, description,
 click target, or actions. If each row can be acted on independently, prefer
 `Item`; if the rows are facts about one entity, prefer `MetadataList`.
+Do not preserve old row/card/table padding classes beside these components; the
+package components already consume the structural row, surface, text, and media
+tokens.
 
 ## 4. Replace form rows