admin-ui-starter-kit 0.5.0 → 0.6.1

package/.agents/skills/admin-ui-components/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: admin-ui-components
+description: "Use when choosing, composing, adding, refactoring, documenting, or migrating admin-ui-starter-kit components across typography, base, composed, features, layout, preview pages, exact package imports, component references, slots/render-props, strings, or layer boundaries."
+---
+
+# Admin UI Components
+
+Use this skill for component work and component selection. It complements
+`component-library-rules`: that skill is the full policy, this skill is the
+short execution path for choosing the right component and keeping package
+surfaces coherent.
+
+## First Reads
+
+1. Read `.agents/skills/component-library-rules/SKILL.md` before touching
+   `src/components/**`.
+2. Read `.agents/skills/component-library-rules/references/components/INDEX.json`
+   before creating or replacing UI. Filter by `layer`, `family`, `tags`, or
+   `description`.
+3. Read only the matching per-component reference file from
+   `.agents/skills/component-library-rules/references/components/`.
+4. If the task is about consumer migration, also read
+   `.agents/skills/admin-ui-consumer-migration/SKILL.md`.
+5. If the task changes token usage, also use `token-system`.
+
+## Component Selection
+
+- Text, labels, headings, and links: `admin-ui-starter-kit/typography`.
+- Buttons and action controls: `base/buttons`.
+- Form rows and fields: `base/forms`; searchable selects: `base/combobox`.
+- Icon/avatar/title/description/action rows: `base/item`.
+- Card shell and repeated panels: `base/cards`.
+- Tables and index cells: `base/table`.
+- Dialogs, drawers, and alert dialogs: `features/overlays`.
+- Filters and query helpers: `features/filters`.
+- Comments, global search, media library, schema form, resource pages, sync,
+  rich text, and similar app-level behavior: `features/*`.
+- Metrics, commerce, admin, data-display, navigation, and timeline cards:
+  `composed/*`.
+- Page, header, sidebar, auth, settings, and shell chrome: `layout/*`.
+
+When local JSX exists only to standardize spacing, height, icon sizing, row
+rhythm, card padding, or table density, prefer the package component that
+already consumes structural tokens.
+
+## Implementation Rules
+
+- Keep layer order: `ui` → `typography` → `base` → `layout`/`composed` →
+  `features`.
+- Do not edit `src/components/ui/**`; wrap shadcn primitives in `base`.
+- Use exact package subpaths in docs and consumer examples. No broad
+  `base`, `composed`, or `features` aggregate imports.
+- Use `Text`, `Heading`, `Label`, and `TextLink` for user-facing text.
+- Use component strings files for user-facing copy.
+- Keep framework behavior in callbacks, fetchers, accessors, render-props, or
+  slots. No router/query/i18n imports in package components.
+- Preserve public DOM hooks: `{kebab-name}--component` on the outer DOM node
+  and `{kebab-name}--region` for named subregions.
+- Prefer slots, render-props, exported partials, and headless hooks over forks.
+
+## Verification
+
+- `npm run lint:architecture`
+- `npm run lint:tokens`
+- `npm run docs:sync-skill -- --check` after preview docs/examples change.
+- `npm run typecheck`
+- `npm run lint`
+- Targeted tests for changed behavior.
+- Browser/Playwright visual pass for user-facing component changes.
+
+Read `references/selection-checklist.md` for the compact pre-edit checklist.

package/.agents/skills/admin-ui-components/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Admin UI Components"
+  short_description: "Choose and modify package components safely"
+  default_prompt: "Use $admin-ui-components to choose package components, inspect generated component references, preserve layer boundaries, and implement admin-ui-starter-kit component work."

package/.agents/skills/admin-ui-components/references/selection-checklist.md

@@ -0,0 +1,23 @@
+# Component Selection Checklist
+
+Run this before writing new JSX or keeping copied consumer UI.
+
+1. Identify the layer: typography, base, composed, features, layout, or service.
+2. Search `references/components/INDEX.json` for an existing component.
+3. Read the specific generated component reference before editing or replacing.
+4. Prefer package primitives:
+   - `Item` for media/title/description/action rows.
+   - `FormField` / `ControlledFormField` for label/control/error rows.
+   - `SmartCard` for cards and grouped panels.
+   - `DataTable` for index tables and selection chrome.
+   - `FilterProvider` / `FilterLayout` for filter state and facets.
+   - `ResourceIndexShell`, `ResourceShowShell`, `TabbedResourceShell`,
+     `SettingsShell`, and `AsideNavShell` for page scaffolding.
+5. If a component needs a missing slot, render-prop, hook, or exported partial,
+   add that seam to the package component instead of forking the preview or
+   consumer page.
+6. If a local component exists only for spacing, density, icon size, table
+   padding, or card rhythm, migrate it to the package component plus structural
+   token overrides.
+7. Verify exact public imports against `package.json` `exports`.
+

package/.agents/skills/admin-ui-consumer-migration/SKILL.md

@@ -18,9 +18,12 @@ When available in the installed package or repo, read these before editing:
 1. `MIGRATION.md` — migration sequence and deletion rules.
 2. `COMPONENT_SELECTION.md` — which component/import to use.
 3. `INTEGRATION.md` — install, provider, exact import, and framework wiring.
-4. `.agents/skills/component-library-rules/references/components/INDEX.json` —
+4. `src/preview/pages/base/css-variables.mdx` or the generated
+   `base__css-variables.md` component reference — compact structural token
+   contract.
+5. `.agents/skills/component-library-rules/references/components/INDEX.json` —
    searchable component index.
-5. `.agents/skills/admin-ui-consumer-migration/references/actions-service.md` —
+6. `.agents/skills/admin-ui-consumer-migration/references/actions-service.md` —
    shared action registry, overlay, form, and lifecycle wiring guide.
 
 Do not bulk-load every component doc. Use the index, then read only the matching
@@ -29,12 +32,14 @@ component file.
 ## Migration order
 
 1. Install package, stylesheet, and `<UIProvider>`.
-2. Replace typography, buttons, badges, cards, and simple display components.
-3. Replace repeated action/list rows with `Item`; replace label/value facts with `MetadataList`.
-4. Replace form rows with `FormField` / `ControlledFormField`, and use package field primitives or comboboxes inside them.
-5. Replace tables, filters, metrics, comments, overlays, and other features.
-6. Replace page/header/sidebar layout surfaces last.
-7. Delete copied local folders only after imports, typecheck, and build are
+2. Remove copied component-family token aliases and map real product overrides
+   to the package structural token contract.
+3. Replace typography, buttons, badges, cards, and simple display components.
+4. Replace repeated action/list rows with `Item`; replace label/value facts with `MetadataList`.
+5. Replace form rows with `FormField` / `ControlledFormField`, and use package field primitives or comboboxes inside them.
+6. Replace tables, filters, metrics, comments, overlays, and other features.
+7. Replace page/header/sidebar layout surfaces last.
+8. Delete copied local folders only after imports, typecheck, and build are
    clean.
 
 When migrating date pickers, install `react-day-picker@^10` for
@@ -53,7 +58,7 @@ Use:
 import { Button } from 'admin-ui-starter-kit/base/buttons';
 import { Text } from 'admin-ui-starter-kit/typography';
 import { Item } from 'admin-ui-starter-kit/base/item';
-import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
+import { MetadataList } from 'admin-ui-starter-kit/composed/data-display';
 import { ControlledFormField, FormField, Input, PasswordInput, SlugField } from 'admin-ui-starter-kit/base/forms';
 import { EnhancedCombobox } from 'admin-ui-starter-kit/base/combobox';
 import { SchemaForm, type SchemaFormSchema, type SchemaFormValues } from 'admin-ui-starter-kit/features/schema-form';
@@ -66,7 +71,7 @@ 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';
+import { MetadataList } from 'admin-ui-starter-kit/composed/data-display/metadata-list';
 ```
 
 If a path is not listed in `package.json` `exports`, treat it as private.
@@ -96,6 +101,35 @@ Do not create local mirrors, barrels, or aliases that hide package imports.
 Agents should replace call-site imports directly unless a wrapper adds routing,
 auth, API, translation, or domain behaviour.
 
+## Structural token migration
+
+The package owns both component implementations and the scale system those
+components consume. In a consuming app, do not preserve copied token aliases
+just because old local components referenced them.
+
+Use this split:
+
+- Theme/color/radius/shadow/dark-light/chart/sidebar overrides map to the
+  shadcn-compatible variables from `src/css/themes/shadcn.default.css`.
+- Typography scale, spacing, density, states, action/control heights, controls,
+  rows, surfaces, icon/avatar sizes, component knobs, and shell dimensions map
+  to standalone token files under `src/css/tokens/`.
+- Start with `--text-scale`, `--space-scale`, and `--density-scale`; then use
+  public structural variables such as `--height-action`, `--height-control`,
+  `--rounded-radius`, `--control-x`, `--row-y`, `--surface-x`, `--space-lg`,
+  `--icon`, `--avatar`, and `--shell-sidebar-width` when a scoped override is
+  truly needed.
+
+Delete or migrate local component-family aliases for action controls, display
+blocks, cards, tables, headers, app shells, and component-specific text roles.
+Normal consumer code should use package components and Tailwind utilities
+generated from structural tokens: `h-control`, `px-control`, `gap-space-*`,
+`py-row-y`, `px-surface`, `size-icon`, and `size-avatar`.
+
+Avoid arbitrary structural values (`text-[...]`, `gap-[...]`, `px-[...]`,
+`size-[...]`) except for genuinely fixed artwork, maps, charts, or preview-only
+canvas cases.
+
 ## Keep app-owned
 
 Do not migrate these into package imports or generic wrappers:
@@ -131,7 +165,7 @@ Review the diff before deleting local folders.
 | Badges | `admin-ui-starter-kit/base/badge` |
 | Card shell | `admin-ui-starter-kit/base/cards` |
 | Icon/avatar/title row | `admin-ui-starter-kit/base/item` |
-| Label/value metadata | `admin-ui-starter-kit/base/display/metadata` |
+| Label/value metadata | `admin-ui-starter-kit/composed/data-display` |
 | Form rows | `admin-ui-starter-kit/base/forms` |
 | Form workflow chrome | `FormSection`, `FormActionsBar`, `ErrorSummary`, `DirtyStateBanner`, `SubmitStateButton` from `admin-ui-starter-kit/base/forms` |
 | Schema-driven settings/config forms | `admin-ui-starter-kit/features/schema-form` |
@@ -140,7 +174,7 @@ Review the diff before deleting local folders.
 | Searchable selects / async resource pickers | `EnhancedCombobox`, `EnhancedComboboxMultiple`, `AsyncResourceCombobox` from `admin-ui-starter-kit/base/combobox` |
 | Date pickers | `admin-ui-starter-kit/base/date-pickers` |
 | Tables / index cells | `DataTable`, `ResourceCell`, `StatusClusterCell`, `DateMetaCell` from `admin-ui-starter-kit/base/table` |
-| Data-view chrome | `admin-ui-starter-kit/base/data-view` |
+| Data-view chrome | `admin-ui-starter-kit/features/data-view` |
 | Filters / filter URL state | `FilterProvider`, `FilterLayout`, `parseFiltersFromQuery`, `serializeFiltersToQuery`, `mergeFilterQuery` from `admin-ui-starter-kit/features/filters` |
 | Comments | `admin-ui-starter-kit/features/comments` |
 | Media picker / product gallery field | `admin-ui-starter-kit/features/media-library` |
@@ -188,6 +222,10 @@ Typography should come from `admin-ui-starter-kit/typography`: `Text`,
 `text-muted-foreground`, or `font-semibold` spans when a package typography
 primitive can express the same intent.
 
+Spacing should come from package components or structural token utilities. Do
+not keep local wrapper components whose only job is to reproduce copied row,
+card, table, or action spacing.
+
 For `react-hook-form`, `ControlledFormField` renders the error text. Pass the
 render-prop `invalid` value to the inner field or `EnhancedCombobox`; use the
 control-level `error` prop only when the control is not wrapped by

package/.agents/skills/admin-ui-consumer-migration/references/package-gap-surfaces.md

@@ -5,7 +5,7 @@ or resource selectors.
 
 ## Index Pages
 
-- Use `ResourceIndexShell` from `admin-ui-starter-kit/layout/resource` for the
+- Use `ResourceIndexShell` from `admin-ui-starter-kit/features/resource` for the
   page header, actions, toolbar, empty/loading/error slots, and content rhythm.
 - Use `DataTable` from `admin-ui-starter-kit/base/table` for row selection,
   selection toolbar, sticky toolbar/header, max body height, and row actions.
@@ -50,3 +50,22 @@ or resource selectors.
 
 Use `services/actions` only when the same action definition needs shared
 loading/error/overlay/toast lifecycle across several package surfaces.
+
+## Tokenization And Local Glue
+
+Do not keep an app-local index shell, settings shell, table wrapper, row
+wrapper, or card wrapper only because it defines copied spacing variables. The
+package surfaces already consume the structural token system:
+
+- controls use `--control-*`;
+- rows, table density, filters, command results, and search results use
+  `--row-*`;
+- cards, empty states, form sections, and feature panels use `--surface-*` and
+  `--space-*`;
+- icons and avatars use `--icon*` and `--avatar*`;
+- shell dimensions use `--shell-header-height` and `--shell-sidebar-width`.
+
+Map real product-level density changes to `--text-scale`, `--space-scale`,
+`--density-scale`, or a narrow structural variable override. Delete local
+component-family aliases for action controls, cards, tables, headers, and app
+shells during migration.

package/.agents/skills/component-library-rules/SKILL.md

@@ -115,7 +115,7 @@ those generic skills is inlined here:
 
 - **Visual taste / "escape generic AI aesthetics"** → see rule 16 (visual evaluation) and the "Tone for visual work" section in `AGENTS.md`. The library voice is calm, neutral, dense without being cramped — admin density, not marketing flash.
 - **Adding a shadcn primitive** → step 0 of [`references/base-wrapper.md`](references/base-wrapper.md): `npx shadcn@latest add <primitive>` lands the file in `src/components/ui/<primitive>.tsx`. Then write the wrapper.
-- **Tailwind v4 + shadcn token architecture** → `src/App.css` is the Tailwind/import entrypoint. Shadcn palette, radius, shadow, and dark/light tokens live in `src/css/themes/default.css`; typography scale, density, component knobs, and base resets live in `src/css/defaults.css`. Read the comment blocks in those CSS files before editing. Do **not** move design tokens into runtime CSS or component-level `style={}` props.
+- **Tailwind v4 + shadcn token architecture** → `src/App.css` is the Tailwind/import entrypoint. Shadcn palette, radius, shadow, dark/light, chart, and sidebar tokens live in the swappable `src/css/themes/shadcn.default.css` adapter. Package-owned states, 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/`. `src/css/themes/default.css` and `src/css/defaults.css` are legacy aggregators only. Read the comment blocks in those CSS files before editing. Do **not** move design tokens into runtime CSS or component-level `style={}` props.
 
 ## 1. Never modify shadcn primitives directly
 
@@ -172,10 +172,11 @@ The `Text` component (`@/components/typography/text`) and `Heading` component (`
 
 **`text-base` is rare.** Use it only for actual hero values. Default to `sm`/`xs`.
 `<Text>` inherits `sm` from `UIProvider` (`typography.defaultTextSize`). Do not
-write `size="sm"` unless you are intentionally pinning the size against provider
-configuration or demonstrating size variants in a preview. Same rule for
-`<Badge size="xs">` and `<Button size="sm">`: the defaults are provider-driven,
-so omit those props at normal call sites.
+write `size="sm"` unless you are intentionally pinning the typography size
+against provider configuration or demonstrating typography variants in a
+preview. Same rule for component scale props such as
+`<Badge size="small">` and `<Button size="small">`: the defaults are
+provider-driven, so omit those props at normal call sites.
 
 Forbidden:
 - `text-[10px]`, `text-[11px]`, `text-[13px]` — pick `xxs` / `xs` / `sm`.
@@ -468,7 +469,7 @@ next reader doesn't think it was forgotten.
 - `muted` / `muted-foreground` — neutral grays
 
 ### Adding new variants
-If you need a new colour variant in `src/css/themes/default.css` (e.g. a "premium" gold):
+If you need a new shadcn-compatible colour variant in `src/css/themes/shadcn.default.css` (e.g. a "premium" gold):
 - Add the variable in BOTH the `:root` light and `.dark` dark scope
 - Add `--color-<name>: var(--<name>)` in `@theme`
 - **Comment it** with what it's for and where it's used
@@ -660,13 +661,28 @@ Two-line rule: if a consumer asks "how do I customize X" and the answer requires
 
 ## 14. Theming surface — beyond shadcn tokens
 
-Shadcn tokens (`--background`, `--foreground`, `--card`, etc.) are the foundation. Beyond them, expose component-level CSS variables in `src/css/defaults.css` under `@theme inline` or `:root` so consumers can rebrand without forking:
+Shadcn tokens (`--background`, `--foreground`, `--card`, etc.) are the foundation and stay in `src/css/themes/shadcn.default.css`. Library states, sizing, typography, spacing, density, controls, rows, surfaces, media sizing, and shell dimensions live in standalone token files under `src/css/tokens/`.
 
-- **Typography scale** — `--text-xxs`, `--text-xs`, `--text-sm`, `--text-base`, `--text-lg`. The `Text`/`Heading` components read from these, so a consumer can resize the entire library at `:root` for denser/sparser dashboards.
-- **Density** — `--row-py`. List rows in command, accordion, tags-input, global-search, and similar list/menu surfaces consume this through `py-(--row-py)`.
-- **Component-specific** — when a single component reasonably needs override (`--filter-chip-h`, `--popover-content-pad`), add a variable and document where it's read.
+Use the right CSS variable layer:
 
-Document each new variable in the owning CSS file with a comment listing the consuming components.
+- **Tailwind utility tokens** go in `@theme inline` when Tailwind should generate a utility from them. Current examples: `--font-*`, `--text-*`, and each paired `--text-*--line-height`.
+- **Runtime inherited knobs** go in `:root` when consumers should tune the library or a subtree without regenerating utilities. Current examples: `--text-scale`, `--space-scale`, `--density-scale`, `--control-height`, `--row-y`, `--surface-x`, `--icon`, `--avatar`, and `--shell-sidebar-width`.
+- **Component-specific overrides** should be avoided unless a real consumer override exists and the value cannot be expressed through the compact structural contract. Do not add unbounded per-instance style props for values that belong in the shared scale.
+
+Token taxonomy:
+
+- **Multipliers** — `--text-scale`, `--space-scale`, `--density-scale`.
+- **Typography** — `--text-xxs` through `--text-2xl` plus `--font-sans` and `--font-mono`.
+- **Spacing** — `--space-2xs` through `--space-2xl`.
+- **Controls** — `--control-height*` and `--control-x*` for buttons, inputs, selects, comboboxes, date picker triggers, and menu/popover triggers.
+- **Rows** — `--row-x` and `--row-y*` for list, command, menu, filter, activity, global-search, and table row rhythm.
+- **Surfaces** — `--surface-x*` and `--surface-y*` for cards, form sections, empty states, and composed feature panels.
+- **Media** — `--icon*` and `--avatar*` for shared icon/avatar sizing.
+- **Shell** — `--shell-header-height` and `--shell-sidebar-width`.
+
+Do not reintroduce component-family structural aliases for action controls, text
+roles, cards, tables, headers, or app shells. Prefer aliasing a documented root
+variable over inventing component-local custom properties in class strings.
 
 ## 15. Hooks colocation
 
@@ -697,9 +713,8 @@ There is exactly **one** library provider: `<UIProvider>` from `@/lib/ui-provide
 - `forms.defaultControlSize`, `forms.defaultLabelSize`
 - `table.defaultSize`
 - `typography.defaultTextSize`
-- `badge.defaultSize`
 - `item.defaultSize`, `item.defaultVariant`
-- `button.defaultSize`, `button.defaultButtonStyle`
+- `button.defaultButtonStyle`
 - `card.defaultPadding`
 - `toast.duration`, `toast.position`
 - `spinner.defaultVariant`
@@ -708,7 +723,7 @@ There is exactly **one** library provider: `<UIProvider>` from `@/lib/ui-provide
 > **Source of truth**: the canonical, up-to-date slice list lives in
 > [`src/lib/ui-provider/types.ts`](../../../src/lib/ui-provider/types.ts) (the `UIConfig` union and its slice types). The bullet list above is informational; trust the file when they disagree.
 
-Implemented as a single zustand store; consumers read via slice hooks (`useMoneyConfig()`, `useBadgeConfig()`, `useItemConfig()`, `useDatesConfig()`, …). Slice-scoped subscriptions: components that read `money` do not re-render when `dates` changes.
+Implemented as a single zustand store; consumers read via slice hooks (`useMoneyConfig()`, `useFormsConfig()`, `useItemConfig()`, `useDatesConfig()`, …). Slice-scoped subscriptions: components that read `money` do not re-render when `dates` changes.
 
 ### Resolution rule (universal)
 
@@ -743,15 +758,15 @@ A provider slice that no consumer reads is a smell — either wire it (read it f
 When a wrapper composes another size-aware base component, **do not pin a literal size to it**. Pinning blocks the resolution chain (`props.X ?? config.X ?? fallback`) so the consumer's `<UIProvider>` override can never reach the inner component.
 
 ```tsx
-// ❌ TextButton always renders BaseButton at size="xs", even if the consumer
-//    set <UIProvider button={{ defaultSize: 'sm' }}>.
-<BaseButton size="xs" {...props} />
+// ❌ TextButton always renders BaseButton at size="small", even if the
+//    consumer set <UIProvider forms={{ defaultControlSize: 'default' }}>.
+<BaseButton size="small" {...props} />
 
 // ✅ Forward the resolved size so BaseButton can apply its own resolution.
 <BaseButton size={resolvedSize} {...props} />
 ```
 
-If the wrapper genuinely needs a narrower size space (e.g. `'xs' | 'sm' | 'base'`), declare its own `size` prop in that narrower type and map it to the inner component's space — but still forward it.
+If the wrapper genuinely needs a narrower size space (usually `'default' | 'small'`), declare its own `size` prop in that narrower type and map it to the inner component's space — but still forward it.
 
 ## 18. Import-path discipline — exactly one path per destination
 
@@ -778,7 +793,7 @@ Published package imports use exact subpaths, not broad aggregates:
 
 - ✅ `admin-ui-starter-kit/typography`
 - ✅ `admin-ui-starter-kit/base/item`
-- ✅ `admin-ui-starter-kit/base/display/metadata`
+- ✅ `admin-ui-starter-kit/composed/data-display`
 - ✅ `admin-ui-starter-kit/composed/cards`
 - ✅ `admin-ui-starter-kit/features/comments`
 - ✅ `admin-ui-starter-kit/layout/page`
@@ -786,7 +801,7 @@ Published package imports use exact subpaths, not broad aggregates:
 - ❌ `admin-ui-starter-kit/composed`
 - ❌ `admin-ui-starter-kit/features`
 - ❌ `admin-ui-starter-kit/ui/tabs`
-- ❌ `admin-ui-starter-kit/base/display/metadata/metadata-list`
+- ❌ `admin-ui-starter-kit/composed/data-display/metadata-list`
 
 The root package entrypoint (`admin-ui-starter-kit`) must stay optional-peer-free:
 provider exports, strings helpers, and `cn` only. Do not re-export `Base`,
@@ -796,9 +811,9 @@ would eagerly load optional peer packages in fresh consumer apps.
 Most public package boundaries are first-level families. A nested subfamily is
 public only when it has an explicit `package.json` export and
 `vite.lib.config.ts` entry. Example: `MetadataList` is intentionally exported
-from `admin-ui-starter-kit/base/display/metadata` so consumers do not need to
+from `admin-ui-starter-kit/composed/data-display` so consumers do not need to
 load the broader `base/display` barrel. Never document file-level paths such as
-`admin-ui-starter-kit/base/display/metadata/metadata-list`.
+`admin-ui-starter-kit/composed/data-display/metadata-list`.
 
 The package `exports` map must list every public family as an exact key:
 `./base/buttons`, `./features/comments`, `./layout/page`, etc. Do not use
@@ -880,7 +895,7 @@ Base-layer references:
 
 Token-level references:
 
-- **`src/App.css` + `src/css/themes/default.css` + `src/css/defaults.css`** — `App.css` is the import entrypoint; `themes/default.css` holds the shadcn palette/radius/shadow mapping; `defaults.css` holds typography font-size variables (`--text-xxs/xs/sm/base/lg`), the density token (`--row-py`), and component knobs (`--popover-content-pad`). Tailwind routes utilities through these variables so consumers can override at `:root`.
+- **`src/App.css` + `src/css/themes/shadcn.default.css` + `src/css/tokens/*`** — `App.css` is the import entrypoint; `themes/shadcn.default.css` holds the swappable shadcn palette/radius/shadow mapping; `tokens/*` holds the compact package contract: text/space/density multipliers, `--text-*`, `--space-*`, `--rounded-radius*`, `--height-action*`, `--height-control*`, `--control-*`, `--row-*`, `--surface-*`, `--icon*`, `--avatar*`, shell dimensions, state extensions, component knobs, and temporary compatibility aliases. Tailwind routes utilities through these variables so consumers can override at `:root`.
 - **`composed/analytics/analytics.strings.ts`** — strings file shape used across composed surfaces.
 
 If a new feature you're adding doesn't structurally resemble at least one of these, you're probably off-pattern. Stop and re-read the rule that applies.
@@ -990,7 +1005,7 @@ See [`src/components/CONVENTIONS.md` §8](../../../src/components/CONVENTIONS.md
 - ❌ "I'll inline a custom popover header here." → Use `Text` + `Heading` + a `border-b` div, with proper paddings.
 - ❌ "The screenshot is too zoomed in to compare." → It's still your problem; fix it for the actual rendered DPI.
 - ❌ "I'll wrap the icon in a `bg-muted` square." → Plain icon usually reads better; only add a container when it's load-bearing.
-- ❌ "I'll bypass the design tokens with a hex." → Use semantic tokens; add a new variant in the owning theme/defaults CSS file with a comment if you genuinely need one.
+- ❌ "I'll bypass the design tokens with a hex." → Use semantic tokens; add a new variant in the owning theme or token layer with a comment if you genuinely need one.
 - ❌ "I'll hardcode 'Cancel' here, it's just temp." → It will not be temp. Use defaultStrings.
 - ❌ "Let me make this row super tight at `py-0.5`." → That's cramped. `py-1.5` minimum unless explicitly compact.
 - ❌ "I'll just `import { useQuery } from '@tanstack/react-query'`." → It's a peer-dep. Accept a `fetcher` prop. Adapter folders no longer exist; the consumer wires their query lib at the call site.

package/.agents/skills/component-library-rules/references/audit-followups.md

@@ -41,7 +41,7 @@ a shared `SelectTriggerChrome` helper that both consume.
 
 Today these composites hardcode `h-9` on their inner SelectTrigger,
 producing a height mismatch when a consumer sets
-`<UIProvider forms={{ defaultControlSize: 'sm' }}>` (32px input next
+`<UIProvider forms={{ defaultControlSize: 'small' }}>` (32px input next
 to 36px trigger):
 
 - `currency-input.tsx:153`
@@ -160,11 +160,11 @@ codemod the AI family. Removes the radius (`rounded-lg` vs `rounded-xl`
 vs `rounded-2xl`) and border-opacity (`border-border` vs `/60` vs `/50`
 vs `/30`) drift in the same pass.
 
-### [H] Drive every list-row from `--row-py` density token
+### [H] Drive every list row from row structural tokens
 
 Three components (`base/command`, `global-search-result-row`, the
-density-token comment block in `src/css/defaults.css`) honour the token; ten others
-inline `py-1.5` / `py-2`:
+row-token comment block in `src/css/defaults.css`) honour the token; ten others
+inline raw row padding:
 
 - `base/navigation/side-nav.tsx:110,151`
 - `base/navigation/action-menu.tsx:206,222,240,258`
@@ -174,7 +174,8 @@ inline `py-1.5` / `py-2`:
 - `features/filters/partials/regular-filter-content.tsx:148`
 - `composed/ai/ai-sources/ai-sources.tsx:196`
 
-Ship: rewrite every menu/list row to `px-3 py-(--row-py)`. This
+Ship: rewrite every menu/list row to `px-row-x py-row-y` or
+`px-row-x py-row-y-sm` where the compact variant is intentional. This
 unblocks `<UIProvider>` density overrides for the whole library
 (rule 17).
 

package/.agents/skills/component-library-rules/references/base-wrapper.md

@@ -103,7 +103,7 @@ import { useFooConfig } from '@/lib/ui-provider';
 
 export function Foo({ size: sizeProp, …rest }) {
     const { defaultSize } = useFooConfig();
-    const size = sizeProp ?? defaultSize ?? 'sm';
+    const size = sizeProp ?? defaultSize ?? 'default';
     /* … */
 }
 ```