admin-ui-starter-kit 0.5.0 → 0.6.2

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/COMPONENT_SELECTION.md

@@ -13,9 +13,10 @@ 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` |
@@ -27,7 +28,7 @@ or documented here, treat it as private.
 | 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 / 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/base/data-view` |
+| 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` |
@@ -44,7 +45,7 @@ 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/layout/resource` |
+| 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` |
@@ -64,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
@@ -143,6 +144,15 @@ 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:
@@ -174,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

@@ -40,10 +40,10 @@ import { Carousel } from 'admin-ui-starter-kit/base/carousel';
 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';
@@ -53,7 +53,7 @@ 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/layout/resource';
+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';
 ```
@@ -65,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.
 
@@ -158,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.

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
 

package/README.md

@@ -63,9 +63,13 @@ exactly your tool.**
 2. **Framework-agnostic by default.** Zero hard-coded calls into Inertia,
    Next.js, react-router, react-query, or any other peer. Every action is a
    callback the consumer wires at the call site.
-3. **Provider-driven defaults.** A single `<UIProvider>` zustand store holds
-   library-wide display defaults (currency, week-start, density, sizes,
-   formatters). Slice-scoped subscriptions, no re-renders on unrelated changes.
+3. **Provider + CSS-token driven defaults.** A single `<UIProvider>` zustand
+   store holds JS-side display defaults (currency, week-start, formatter
+   choices). Visual scale lives in standalone token layers under
+   `src/css/tokens/`: `--text-scale`, `--space-scale`, `--density-scale`,
+   normal `--text-*` sizes, shared action/control height, row, surface, media,
+   and shell variables. Shadcn palette, radius, and shadow tokens stay in the
+   swappable `src/css/themes/shadcn.default.css` adapter.
 4. **Strings always overridable.** Every user-facing string flows through the
    `useStrings(defaults, override)` deep-merge pattern. Consumers wire their
    own i18n at the call site, the library imports zero i18n packages.
@@ -165,15 +169,27 @@ import { UIProvider } from 'admin-ui-starter-kit/ui-provider';
 <UIProvider config={{
   money: { defaultCurrency: 'USD', locale: 'en-US' },
   dates: { weekStartsOn: 1, format: 'dd MMM yyyy' },
-  table: { defaultSize: 'xs' },
-  badge: { defaultSize: 'xs' },
-  item:  { defaultSize: 'sm' },
+  forms: { defaultControlSize: 'default', defaultLabelSize: 'default' },
+  table: { defaultSize: 'small' },
+  button: { defaultButtonStyle: 'solid' },
+  item:  { defaultSize: 'default' },
 }}>
   <App />
 </UIProvider>
 ```
 
 The provider is locked at first mount; pass everything once at the root.
+For sizing and spacing, prefer the calibrated package scale (`default` /
+`small`) plus structural CSS variables such as `--control-height`,
+`--control-x`, `--row-y`, `--surface-x`, and `--space-scale` over repeated
+per-component size props.
+
+Structural scale is intentionally small. Tune global UI shape with
+`--text-scale`, `--space-scale`, and `--density-scale` first; use the public
+`--space-*`, `--control-*`, `--row-*`, `--surface-*`, `--icon*`, `--avatar*`,
+and shell variables when a product needs a precise override. Do not recreate
+old component-family aliases such as action, card, table, header, or app-shell
+spacing tokens in consuming apps.
 
 ### 6. Optional action runtime
 
@@ -294,7 +310,10 @@ can use `modality.formId` with `getFormProps(...)` in the render context.
 This package ships AI skills for Claude Code and other agents:
 
 - `component-library-rules` — maintainer rules for editing this library.
+- `admin-ui-components` — component selection, layer, and reference workflow.
+- `token-system` — shadcn theme + structural token workflow.
 - `admin-ui-consumer-migration` — consumer-app migration rules and guardrails.
+- `component-quality-pass` — route, visual, API, token, and test audit workflow.
 
 After installing the package:
 
@@ -302,11 +321,11 @@ After installing the package:
 npx admin-ui-starter-kit-install-skill
 ```
 
-Copies both skills into your project's `.claude/skills/` and
+Copies the 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`)
+- `--skill=all|component-library-rules|admin-ui-components|token-system|admin-ui-consumer-migration|component-quality-pass` (default `all`)
 - `--target=claude|agents|both` (default `both`) — pick which directory to install into.
 - `--force` — overwrite without prompting.
 
@@ -437,10 +456,10 @@ Import per component family. This keeps optional peers isolated: importing
 ```tsx
 import { Text } from 'admin-ui-starter-kit/typography';
 import { Button } from 'admin-ui-starter-kit/base/buttons';
-import { Frame, FramePanel } from 'admin-ui-starter-kit/base/frame';
+import { SmartCard } from 'admin-ui-starter-kit/base/cards';
 import { Item, ItemGroup, ItemMedia, ItemContent, ItemTitle } from 'admin-ui-starter-kit/base/item';
 import { ControlledFormField, FormSection, Input, PasswordInput } from 'admin-ui-starter-kit/base/forms';
-import { DataViewShell, DataViewToolbar } from 'admin-ui-starter-kit/base/data-view';
+import { DataViewShell, DataViewToolbar } from 'admin-ui-starter-kit/features/data-view';
 import { AsyncResourceCombobox, EnhancedCombobox } from 'admin-ui-starter-kit/base/combobox';
 import { DataTable, ResourceCell, StatusClusterCell } from 'admin-ui-starter-kit/base/table';
 import { Badge } from 'admin-ui-starter-kit/base/badge';
@@ -453,10 +472,11 @@ import { ResourceSelectorCard } from 'admin-ui-starter-kit/composed/data-display
 import { ChartCard } from 'admin-ui-starter-kit/composed/analytics';
 import { Comments } from 'admin-ui-starter-kit/features/comments';
 import { parseFiltersFromQuery, serializeFiltersToQuery } from 'admin-ui-starter-kit/features/filters';
+import { Container, Section } from 'admin-ui-starter-kit/layout/containers';
 import { Dialog, Drawer } from 'admin-ui-starter-kit/features/overlays';
 import { SchemaForm } from 'admin-ui-starter-kit/features/schema-form';
 import { HeaderToolButton, HeaderToolPopover } from 'admin-ui-starter-kit/layout/header';
-import { ResourceIndexShell, ResourceShowShell, TabbedResourceShell } from 'admin-ui-starter-kit/layout/resource';
+import { ResourceIndexShell, ResourceShowShell, TabbedResourceShell } 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';
 import { useStrings } from 'admin-ui-starter-kit/lib/strings';
@@ -468,7 +488,7 @@ have an isolated entrypoint so consumers do not pull Recharts through unrelated
 display helpers:
 
 ```tsx
-import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
+import { MetadataList } from 'admin-ui-starter-kit/composed/data-display';
 import { ChartContainer } from 'admin-ui-starter-kit/base/display/chart';
 ```
 
@@ -477,14 +497,14 @@ Safe public entrypoint shapes:
 - `admin-ui-starter-kit/ui-provider`
 - `admin-ui-starter-kit/typography`
 - `admin-ui-starter-kit/base/buttons`, `admin-ui-starter-kit/base/item`, etc.
-- `admin-ui-starter-kit/base/data-view`
+- `admin-ui-starter-kit/features/data-view`
 - `admin-ui-starter-kit/base/table`
 - `admin-ui-starter-kit/base/combobox`
-- `admin-ui-starter-kit/base/display/metadata`
+- `admin-ui-starter-kit/composed/data-display`
 - `admin-ui-starter-kit/base/display/chart`
 - `admin-ui-starter-kit/composed/cards`, `admin-ui-starter-kit/composed/analytics`, `admin-ui-starter-kit/composed/admin`, etc.
 - `admin-ui-starter-kit/features/comments`, `admin-ui-starter-kit/features/filters`, `admin-ui-starter-kit/features/schema-form`, etc.
-- `admin-ui-starter-kit/layout` and exact layout families such as `admin-ui-starter-kit/layout/page`, `admin-ui-starter-kit/layout/resource`, `admin-ui-starter-kit/layout/settings`
+- `admin-ui-starter-kit/layout` and exact layout families such as `admin-ui-starter-kit/layout/page`, `admin-ui-starter-kit/features/resource`, `admin-ui-starter-kit/layout/settings`
 - `admin-ui-starter-kit/services/actions`
 - `admin-ui-starter-kit/lib/strings`
 - `admin-ui-starter-kit/lib/utils`
@@ -537,8 +557,20 @@ import { DropdownMenu, DropdownMenuContent, DropdownMenuTrigger } from 'admin-ui
 
 ## Build your own stylesheet
 
-The pre-built `style.css` is convenient but you may already run Tailwind in
-your app. To skip the pre-built CSS:
+The pre-built `style.css` is the recommended default. To publish editable local
+copies of the package theme/default token layers:
+
+```bash
+npx admin-ui-starter-kit-publish-theme
+```
+
+This 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` when you want package CSS plus
+checked-in token overrides.
+
+If you intentionally skip the pre-built CSS and rebuild Tailwind in your app:
 
 1. Don't import `admin-ui-starter-kit/style.css`.
 2. Add the kit's source to your Tailwind `content`:
@@ -548,9 +580,11 @@ your app. To skip the pre-built CSS:
    content: ['./node_modules/admin-ui-starter-kit/dist/**/*.{js,cjs}'],
    ```
 
-3. Copy the design tokens from
-   `node_modules/admin-ui-starter-kit/src/App.css` into your own root
-   stylesheet (`@theme` block + `:root` / `.dark` custom-property scopes).
+3. Start from the generated `src/styles/admin-ui/source.css`. Keep shadcn
+   color, radius, shadow, dark/light, chart, and sidebar values in the theme
+   layer; keep package states, structural typography, spacing, density,
+   action/control heights, rows, surfaces, media, shell, and component knobs in
+   the defaults layer.
 
 ---