admin-ui-starter-kit 0.5.0 → 0.6.1

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

@@ -0,0 +1,326 @@
+---
+id: services/hooks
+title: "Hooks reference"
+description: "Public hook import boundaries for provider defaults, layout helpers, action lifecycle, and feature headless state."
+layer: services
+family: "Hooks"
+sourcePath: src/lib/ui-provider, src/components/layout/hooks, src/services/actions, src/components/features/*/hooks
+examples:
+  - HookImportMatrix
+  - HookRules
+  - FeatureHookList
+  - InternalHooksNotice
+  - HookRouteShortcuts
+imports:
+  - @/components/base/badge
+  - @/components/base/buttons
+  - @/components/base/cards
+  - @/components/base/display
+  - @/components/typography
+tags:
+  - services
+  - hooks
+  - reference
+  - public
+  - hook
+  - import
+---
+
+# Hooks reference
+
+Public hook import boundaries for provider defaults, layout helpers, action lifecycle, and feature headless state.
+
+**Layer:** `services`
+**Source:** `src/lib/ui-provider, src/components/layout/hooks, src/services/actions, src/components/features/*/hooks`
+
+## Overview
+
+Hooks are public only when they are exported from an exact package subpath.
+There is no broad `admin-ui-starter-kit/hooks` entrypoint. This keeps optional
+peers isolated, keeps feature state beside the feature it controls, and prevents
+private implementation helpers from becoming accidental API.
+
+<Example name="HookImportMatrix" source={examplesSource} layout="flush">
+	<Examples.HookImportMatrix />
+</Example>
+
+## Import rules
+
+<Example name="HookRules" source={examplesSource} layout="flush">
+	<Examples.HookRules />
+</Example>
+
+Use the same boundary as the thing you are composing:
+
+<CodeBlock language="tsx" code={`import { useButtonConfig, useDatesConfig } from 'admin-ui-starter-kit/ui-provider';
+import { useActivePath, useCommandShortcut } from 'admin-ui-starter-kit/layout/hooks';
+import { useLocalAction, useActionSurface } from 'admin-ui-starter-kit/services/actions';
+import { useGlobalSearch } from 'admin-ui-starter-kit/features/global-search';
+import { useFilters } from 'admin-ui-starter-kit/features/filters';`} />
+
+Do not import hooks from `dist/`, source paths, broad aggregate paths, or
+internal aliases. If a hook is not exported from a public package subpath, it is
+not part of the package contract.
+
+## Provider hooks
+
+`admin-ui-starter-kit/ui-provider` exports `<UIProvider>`, `getUIConfig`, and
+slice hooks such as `useMoneyConfig`, `useDatesConfig`, `useCommentsConfig`,
+`useFiltersConfig`, `useFormsConfig`, `useTableConfig`,
+`useTypographyConfig`, `useItemConfig`, `useButtonConfig`,
+`useCardConfig`, `useToastConfig`, `useSpinnerConfig`, and `useMediaConfig`.
+
+Provider hooks are read-only display defaults. They do not carry per-mount data,
+runtime callbacks, translations, resource registries, or routing behavior. The
+component resolution rule remains:
+
+<CodeBlock language="ts" code={`props.value ?? useFooConfig().value ?? hardcodedFallback`} />
+
+## Layout hooks
+
+`admin-ui-starter-kit/layout/hooks` exports layout-only helpers:
+
+- `useLayoutLinkRenderer` for a shared router-agnostic `renderLink` contract.
+- `useActivePath` for active navigation checks.
+- `useCommandShortcut` for command/search keyboard shortcut handling.
+
+These hooks support package layout shells. They do not know about app routers;
+consumers pass link renderers and current paths through props.
+
+## Action hooks
+
+`admin-ui-starter-kit/services/actions` exports hooks for the shared action
+runtime:
+
+- `useRegisterActions` registers definitions in the current or explicit scope.
+- `useLocalAction` registers one component-local definition for incremental
+  migration.
+- `useAction` resolves one action by id.
+- `useActionSurface` resolves all actions for a surface such as `page`,
+  `table-row`, `card`, or `command`.
+- `useActiveAction` reads the action currently rendered by
+  `ActionOverlayOutlet`.
+- `useActionSnapshot` reads the complete registry and run-state snapshot.
+- `useActionScope` reads the current scope id.
+
+Use these only inside `<ActionProvider>`.
+
+## Feature hooks
+
+<Example name="FeatureHookList" source={examplesSource} layout="flush">
+	<Examples.FeatureHookList />
+</Example>
+
+Feature hooks are headless state machines or composition helpers for their own
+feature. They stay in the feature package so consumers can install and import
+only the surfaces they actually use.
+
+## Private helpers
+
+<Example name="InternalHooksNotice" source={examplesSource} layout="flush">
+	<Examples.InternalHooksNotice />
+</Example>
+
+`src/hooks` is a source-level implementation area, not a package export. Global
+helpers there can support the library internals, but consuming apps should rely
+on public hooks from `ui-provider`, `layout/hooks`, `services/actions`, or exact
+feature subpaths.
+
+## Next
+
+<Example name="HookRouteShortcuts" source={examplesSource} layout="center">
+	<Examples.HookRouteShortcuts />
+</Example>
+
+## Examples
+
+```tsx
+import {
+	Braces,
+	Component,
+	Filter,
+	LayoutDashboard,
+	MousePointerClick,
+	PackageCheck,
+	Route,
+	Search,
+	Settings2,
+	ShieldCheck,
+	} from 'lucide-react';
+
+import { Badge } from '@/components/base/badge';
+import { Button } from '@/components/base/buttons';
+import { SmartCard } from '@/components/base/cards';
+import { IconBadge,
+} from '@/components/base/display';
+import { Text } from '@/components/typography';
+
+const publicSurfaces = [
+	{
+		icon: Settings2,
+		title: 'UIProvider hooks',
+		importPath: 'admin-ui-starter-kit/ui-provider',
+		description: 'Read library-wide display defaults such as money, dates, typography, controls, cards, and media.',
+		tone: 'primary',
+		badges: ['useMoneyConfig', 'useDatesConfig', 'useFormsConfig', 'useMediaConfig'],
+	},
+	{
+		icon: LayoutDashboard,
+		title: 'Layout hooks',
+		importPath: 'admin-ui-starter-kit/layout/hooks',
+		description: 'Share layout-specific link rendering, active path checks, and command keyboard shortcut behavior.',
+		tone: 'info',
+		badges: ['useLayoutLinkRenderer', 'useActivePath', 'useCommandShortcut'],
+	},
+	{
+		icon: MousePointerClick,
+		title: 'Action hooks',
+		importPath: 'admin-ui-starter-kit/services/actions',
+		description: 'Resolve registered actions, local actions, surfaces, active action state, and action snapshots.',
+		tone: 'warning',
+		badges: ['useLocalAction', 'useActionSurface', 'useAction', 'useRegisterActions'],
+	},
+	{
+		icon: Component,
+		title: 'Feature hooks',
+		importPath: 'admin-ui-starter-kit/features/<feature>',
+		description: 'Use the headless state machine exported by the exact feature package you render.',
+		tone: 'success',
+		badges: ['useGlobalSearch', 'useFilters', 'useComments', 'useMediaLibrary'],
+	},
+] as const;
+
+const rules = [
+	['Exact subpaths only', 'Hooks import from the same public package boundary as their owning component or service.'],
+	['No framework imports', 'Hooks expose state, callbacks, and descriptors. The consuming app wires routing, fetching, i18n, auth, and query libraries.'],
+	['Feature hooks are local', 'A hook that only belongs to one feature ships from that feature subpath, not from a global hooks barrel.'],
+] as const;
+
+const featureHooks = [
+	['Global search', 'useGlobalSearch', 'features/global-search'],
+	['Filters', 'useFilters, useAsyncOptions, useFilterGroups', 'features/filters'],
+	['Comments', 'useComments, useAttachmentUpload, useReferencePicker', 'features/comments'],
+	['Mentions', 'useMentions, useMentionsSearch', 'features/mentions'],
+	['Suggestions', 'useSuggestions', 'features/suggestions'],
+	['Media library', 'useMediaLibrary', 'features/media-library'],
+	['Schema form', 'useSchemaForm', 'features/schema-form'],
+	['Overlays', 'useOverlayActions, useNativeDialog', 'features/overlays'],
+] as const;
+
+export function HookImportMatrix() {
+	return (
+		<div className="grid gap-3 md:grid-cols-2">
+			{publicSurfaces.map((surface) => (
+				<SmartCard
+					key={surface.title}
+					surface="framed"
+					padding="default"
+					className="h-full"
+					icon={<IconBadge icon={surface.icon} tone={surface.tone} shape="square" />}
+					title={surface.title}
+					description={surface.description}
+					footerText={surface.importPath}
+				>
+					<div className="flex flex-wrap gap-2">
+						{surface.badges.map((badge) => (
+							<Badge key={badge} variant="secondary">
+								{badge}
+							</Badge>
+						))}
+					</div>
+				</SmartCard>
+			))}
+		</div>
+	);
+}
+
+export function HookRules() {
+	return (
+		<div className="grid gap-3 md:grid-cols-3">
+			{rules.map(([title, description]) => (
+				<SmartCard key={title} surface="framed" padding="default">
+					<IconBadge icon={ShieldCheck} tone="success" shape="square" />
+					<div className="mt-3">
+						<Text weight="semibold">{title}</Text>
+						<Text size="xs" type="secondary" className="mt-1">
+							{description}
+						</Text>
+					</div>
+				</SmartCard>
+			))}
+		</div>
+	);
+}
+
+export function FeatureHookList() {
+	return (
+		<SmartCard
+			title="Feature hooks ship with their feature"
+			description="Import the hook from the exact feature package so optional peers and examples stay isolated."
+			icon={<IconBadge icon={Search} tone="info" shape="square" size="default" />}
+		>
+			<div className="grid gap-2">
+				{featureHooks.map(([label, hooks, path]) => (
+					<div key={label} className="grid gap-2 rounded-md border bg-background px-3 py-2.5 md:grid-cols-[10rem_minmax(0,1fr)]">
+						<Text weight="semibold">{label}</Text>
+						<div className="min-w-0">
+							<Text size="xs" type="secondary" className="break-words">
+								{hooks}
+							</Text>
+							<Text size="xs" type="discrete" className="mt-1 break-all font-mono">
+								admin-ui-starter-kit/{path}
+							</Text>
+						</div>
+					</div>
+				))}
+			</div>
+		</SmartCard>
+	);
+}
+
+export function InternalHooksNotice() {
+	return (
+		<SmartCard
+			surface="framed"
+			padding="default"
+			icon={<IconBadge icon={PackageCheck} tone="warning" shape="square" />}
+			title="src/hooks is not a public package surface"
+			description="Global implementation hooks such as use-debounce, use-mobile, and file helpers can support package internals, but consumers should only import hooks from exact exported package subpaths."
+		>
+			<div className="flex flex-wrap gap-2">
+				<Badge variant="secondary">No admin-ui-starter-kit/hooks</Badge>
+				<Badge variant="secondary">No dist file paths</Badge>
+				<Badge variant="secondary">No private aliases</Badge>
+			</div>
+		</SmartCard>
+	);
+}
+
+export function HookRouteShortcuts() {
+	return (
+		<div className="flex flex-wrap gap-2">
+			<Button href="#/services/actions" icon={Braces}>
+				Actions service
+			</Button>
+			<Button href="#/features/global-search" buttonStyle="outline" icon={Search}>
+				Global search hooks
+			</Button>
+			<Button href="#/features/filters" buttonStyle="outline" icon={Filter}>
+				Filter hooks
+			</Button>
+			<Button href="#/layout/page" buttonStyle="outline" icon={Route}>
+				Layout contracts
+			</Button>
+		</div>
+	);
+}
+```
+
+## Example exports
+
+- `HookImportMatrix`
+- `HookRules`
+- `FeatureHookList`
+- `InternalHooksNotice`
+- `HookRouteShortcuts`
+

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

@@ -58,7 +58,7 @@ export function Sizes() {
 								<Button size="xs">xs</Button>
 								<Button size="sm">sm</Button>
 								<Button size="default">default</Button>
-								<Button size="lg">lg</Button>
+								<Button size="default">lg</Button>
 							</Row>
 		</>
 	);

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

@@ -66,7 +66,7 @@ export function ItemsList() {
 										<ItemDescription>Sarah Smitha — 2,450 USD</ItemDescription>
 									</ItemContent>
 									<ItemFooter>
-										<Button size="sm" variant="outline">Open</Button>
+										<Button size="default" variant="outline">Open</Button>
 									</ItemFooter>
 								</Item>
 								<Item>

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

@@ -73,7 +73,7 @@ export function InputExample() {
 }
 
 export function TextareaExample() {
-	const [body, setBody] = useState('');
+	const [body, setBody] = useState('Write a short internal note for the operations team.');
 	return (
 		<>
 			<Textarea placeholder="Multi-line input…" value={body} onChange={(e) => setBody(e.target.value)} />

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

@@ -42,6 +42,7 @@ import { Button } from '@/components/ui/button';
 import {
 	DropdownMenu,
 	DropdownMenuContent,
+	DropdownMenuGroup,
 	DropdownMenuItem,
 	DropdownMenuLabel,
 	DropdownMenuSeparator,
@@ -50,6 +51,7 @@ import {
 import {
 	ContextMenu,
 	ContextMenuContent,
+	ContextMenuGroup,
 	ContextMenuItem,
 	ContextMenuLabel,
 	ContextMenuSeparator,
@@ -86,10 +88,12 @@ export function DropdownMenuExample() {
 			<DropdownMenu>
 				<DropdownMenuTrigger render={(p) => <Button variant="outline" {...p}>Open menu</Button>} />
 				<DropdownMenuContent>
-					<DropdownMenuLabel>Actions</DropdownMenuLabel>
-					<DropdownMenuSeparator />
-					<DropdownMenuItem><Edit className="size-3.5" /> Edit</DropdownMenuItem>
-					<DropdownMenuItem><Copy className="size-3.5" /> Duplicate</DropdownMenuItem>
+					<DropdownMenuGroup>
+						<DropdownMenuLabel>Actions</DropdownMenuLabel>
+						<DropdownMenuSeparator />
+						<DropdownMenuItem><Edit className="size-3.5" /> Edit</DropdownMenuItem>
+						<DropdownMenuItem><Copy className="size-3.5" /> Duplicate</DropdownMenuItem>
+					</DropdownMenuGroup>
 					<DropdownMenuSeparator />
 					<DropdownMenuItem variant="destructive"><Trash2 className="size-3.5" /> Delete</DropdownMenuItem>
 				</DropdownMenuContent>
@@ -131,7 +135,7 @@ export function NavigationMenuExample() {
 					<NavigationMenuItem>
 						<NavigationMenuTrigger>Operations</NavigationMenuTrigger>
 						<NavigationMenuContent>
-							<div className="grid w-[360px] gap-1">
+							<div className="grid w-90 gap-1">
 								<NavigationMenuLink href="#orders">
 									<ExternalLink className="size-4" />
 									<div>
@@ -168,10 +172,12 @@ export function ContextMenuRightClick() {
 					</div>
 				</ContextMenuTrigger>
 				<ContextMenuContent>
-					<ContextMenuLabel>File</ContextMenuLabel>
-					<ContextMenuSeparator />
-					<ContextMenuItem><Edit className="size-3.5" /> Rename</ContextMenuItem>
-					<ContextMenuItem><Copy className="size-3.5" /> Copy</ContextMenuItem>
+					<ContextMenuGroup>
+						<ContextMenuLabel>File</ContextMenuLabel>
+						<ContextMenuSeparator />
+						<ContextMenuItem><Edit className="size-3.5" /> Rename</ContextMenuItem>
+						<ContextMenuItem><Copy className="size-3.5" /> Copy</ContextMenuItem>
+					</ContextMenuGroup>
 					<ContextMenuSeparator />
 					<ContextMenuItem variant="destructive"><Trash2 className="size-3.5" /> Delete</ContextMenuItem>
 				</ContextMenuContent>

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

@@ -37,9 +37,9 @@ export function Lines() {
 	return (
 		<>
 			<Col>
-								<Skeleton className="h-4 w-[80%]" />
-								<Skeleton className="h-4 w-[60%]" />
-								<Skeleton className="h-4 w-[40%]" />
+								<Skeleton className="h-4 w-4/5" />
+								<Skeleton className="h-4 w-3/5" />
+								<Skeleton className="h-4 w-2/5" />
 							</Col>
 		</>
 	);

package/.agents/skills/component-library-rules/references/consumer-wiring.md

@@ -128,8 +128,8 @@ import { UIProvider } from 'admin-ui-starter-kit/ui-provider';
 <UIProvider config={{
     money: { defaultCurrency: 'EUR', locale: 'de-DE' },
     dates: { weekStartsOn: 1, format: 'dd.MM.yyyy' },
-    button: { defaultSize: 'sm' },
-    badge: { defaultSize: 'xs' },
+    forms: { defaultControlSize: 'small', defaultLabelSize: 'small' },
+    button: { defaultButtonStyle: 'solid' },
 }}>
     <App />
 </UIProvider>

package/.agents/skills/component-library-rules/references/history.md

@@ -27,13 +27,13 @@ Goal: introduce the new abstraction layer pieces that everything downstream will
    - Captures the recurring "trigger → header → command list" pattern from filter facets.
    - Slots: `header`, `footer`, `empty`, `loading`.
    - Render-prop: `renderItem={(item) => …}`.
-4. **Typography tokens** in `App.css` `@theme`
-   - `--text-xxs: 0.6875rem`, `--text-xs: 0.75rem`, `--text-sm: 0.8125rem`, `--text-base: 0.875rem`, `--text-lg: 1rem`.
-   - Rewire `Text` size scale to read these via `font-size: var(--text-xs)` etc.
-   - Document each in a comment.
-5. **Density tokens** in `App.css`
-   - `--row-py-tight: 0.25rem`, `--row-py-default: 0.5rem`, `--row-py-loose: 0.625rem`.
-   - Add `data-density="default|tight|loose"` data attribute pattern documented in `App.css`.
+4. **Typography tokens** in `src/css/defaults.css` `@theme inline`
+   - `--text-xxs` through `--text-2xl`, generated from `--text-scale`.
+   - Rewire `Text` size scale to read these via normal text utilities.
+   - Document the public contract in the CSS variables page.
+5. **Density and row tokens** in `src/css/defaults.css`
+   - `--row-y-sm`, `--row-y`, and `--row-y-lg`, generated from `--density-scale`.
+   - Add `data-density="compact|comfortable"` data attribute pattern documented in `defaults.css`.
 
 Verification: snapshot the showcase before/after — pixel diff should be near-zero.
 
@@ -148,7 +148,7 @@ Verification: each preview page should be able to demonstrate at least one slot/
     grep -rn "text-\[" src/components src/preview --include='*.tsx'
     # replace each with semantic Text size or rewire to typography variables
     ```
-33. **Apply density tokens** to list rows in `filters`, `global-search`, `comments`, `metrics`, `activities`. Rows that are currently `py-2`/`py-2.5` consume `var(--row-py-default)` etc.
+33. **Apply row tokens** to list rows in `filters`, `global-search`, `comments`, `metrics`, `activities`. Rows consume `px-row-x` plus `py-row-y`, `py-row-y-sm`, or `py-row-y-lg`.
 34. **Audit `Heading` usage** — confirm h1/h2 are only used in actual page-title contexts, not section headers (those should be `text-base` semibold per the rule).
 
 ---
@@ -198,8 +198,8 @@ deleting every `adapters/$framework/` folder + every peer-dep stub.
     initialized with library-wide defaults. Slice selectors per concern
     (`useMoneyConfig`, `useDatesConfig`, `useCommentsConfig`, …).
 47. **Base + composed read selectors** — `Money` / `MoneyDisplay` /
-    `MoneyInput` via `useMoneyConfig`; `Badge` via `useBadgeConfig`;
-    `SmartCard` via `useCardConfig`; `Button` via `useButtonConfig`;
+    `MoneyInput` via `useMoneyConfig`; `Badge` via display CSS tokens;
+    `SmartCard` via `useCardConfig`; `Button` style via `useButtonConfig`;
     timelines / activity-feed / event-log via `useDatesConfig`. Per-mount
     props always win.
 48. **Delete library-side providers** — `CommentsProvider` and

package/.agents/skills/component-library-rules/references/import-paths.md

@@ -27,7 +27,7 @@ admin-ui-starter-kit                 # provider, strings helpers, cn only
 admin-ui-starter-kit/ui-provider
 admin-ui-starter-kit/typography
 admin-ui-starter-kit/base/<family>
-admin-ui-starter-kit/base/display/metadata
+admin-ui-starter-kit/composed/data-display
 admin-ui-starter-kit/composed/<family>
 admin-ui-starter-kit/features/<feature>
 admin-ui-starter-kit/layout
@@ -52,7 +52,7 @@ only when it has an explicit `package.json` export and `vite.lib.config.ts`
 entry. Current intentional nested subfamily:
 
 ```
-admin-ui-starter-kit/base/display/metadata   # MetadataList
+admin-ui-starter-kit/composed/data-display   # MetadataList
 ```
 
 Examples of blocked package paths:
@@ -60,7 +60,7 @@ Examples of blocked package paths:
 ```
 admin-ui-starter-kit/base/navigation/dropdown-menu
 admin-ui-starter-kit/features/comments/partials/comment-composer
-admin-ui-starter-kit/base/display/metadata/metadata-list
+admin-ui-starter-kit/composed/data-display/metadata-list
 ```
 
 If a component is not exported from its family index, add it to that family

package/.agents/skills/component-library-rules/references/item-pattern.md

@@ -32,7 +32,7 @@ Resolve through `<UIProvider>` via the `useItemConfig()` slice:
 | `item.defaultSize` | `'sm'` | `xs` (dropdowns), `sm` (admin density, library default), `default` (settings rows). |
 | `item.defaultVariant` | `'default'` | `'default'` (transparent), `'outline'` (bordered card-on-card), `'muted'` (inset list). |
 
-Resolution order: `props.size ?? useItemConfig().defaultSize ?? 'sm'`. Same for
+Resolution order: `props.size ?? useItemConfig().defaultSize ?? 'default'`. Same for
 variant. Omit the prop unless you're intentionally pinning the size against
 provider configuration.
 
@@ -78,7 +78,7 @@ provider configuration.
 ### Body-weight title (contact details, line items)
 
 ```tsx
-<Item size="xs" className="px-0">
+<Item size="small" className="px-0">
   <ItemMedia variant="icon" className="text-muted-foreground"><Phone /></ItemMedia>
   <ItemContent>
     <ItemTitle bold={false}>{phone}</ItemTitle>
@@ -161,7 +161,7 @@ provider configuration.
 3. Strip the bespoke `<Text weight="semibold">` and
    `<Text size="xs" type="secondary">` — `ItemTitle` / `ItemDescription`
    handle those.
-4. Drop manual padding overrides; the size token (`xs` / `sm` / `default`)
+4. Drop manual padding overrides; the component scale (`small` / `default`)
    provides density.
 5. If multiple rows render in a list, wrap them in `<ItemGroup>` so the
    group gap follows size.

package/.agents/skills/component-library-rules/references/layout.md

@@ -40,11 +40,13 @@ src/components/layout/
 3. **Reach into `ui/` only via the matching `base/` wrapper.** The
    sidebar/sheet primitives are wrapped in `base/sidebar/` and
    `base/sheet/`; layout imports those, not the raw shadcn files.
-4. **Admin-density typography.** `Badge size="xs"`, `Button size="sm"`,
-   icon-only header controls use `icon-sm`. Primary labels and row text
-   default to `Text size="sm"`; descriptions and helper copy use
-   `Text size="xs"`. Don't push beyond `Text size="base"` in layout —
-   page hierarchy belongs in `PageHeader`.
+4. **Admin-density typography and scale.** Omit routine `size` props so
+   `<UIProvider>` defaults can flow through; use `size="small"` only for
+   intentional compact layout chrome, and use `icon-small` for icon-only
+   header controls. Primary labels and row text use the inherited `Text`
+   default; descriptions and helper copy use `Text size="xs"`. Don't push
+   beyond `Text size="base"` in layout — page hierarchy belongs in
+   `PageHeader`.
 
 ## Navigation contract — `renderLink`
 

package/.agents/skills/component-library-rules/references/testing.md

@@ -39,11 +39,11 @@ afterEach(() => {
     resetUIConfig();
 });
 
-it('respects the configured badge size', () => {
-    applyUIConfig({ badge: { defaultSize: 'sm' } });
-    render(<Badge>x</Badge>);
-    expect(screen.getByText('x').closest('[data-slot="badge"]'))
-        .toHaveClass('px-2', 'py-1', 'text-xs');
+it('respects the configured form control size', () => {
+    applyUIConfig({ forms: { defaultControlSize: 'small' } });
+    render(<Button>Save</Button>);
+    expect(screen.getByRole('button', { name: 'Save' }))
+        .toHaveClass('h-control-sm', 'text-xs');
 });
 ```
 

package/.agents/skills/component-library-rules/references/ui-provider.md

@@ -13,8 +13,7 @@ Open this when adding a slice to `<UIProvider>` or wiring an existing slice into
 - `forms.defaultControlSize`, `forms.defaultLabelSize`
 - `table.defaultSize`
 - `typography.defaultTextSize`
-- `badge.defaultSize`
-- `button.defaultSize`, `button.defaultButtonStyle`
+- `button.defaultButtonStyle`
 - `card.defaultPadding`
 - `toast.duration`, `toast.position`
 - `spinner.defaultVariant`
@@ -39,11 +38,11 @@ The store is initialized with `DEFAULT_UI_CONFIG`, so a component without `<UIPr
 ### Worked example
 
 ```tsx
-import { useBadgeConfig, type BadgeSize } from '@/lib/ui-provider';
+import { useFormsConfig, type FormControlSize } from '@/lib/ui-provider';
 
-export function Badge({ size: sizeProp, … }: BadgeProps) {
-    const { defaultSize } = useBadgeConfig();
-    const size: BadgeSize = sizeProp ?? defaultSize ?? 'xs';
+export function Input({ size: sizeProp, … }: InputProps) {
+    const { defaultControlSize } = useFormsConfig();
+    const size: FormControlSize = sizeProp ?? defaultControlSize ?? 'default';
     /* … */
 }
 ```
@@ -84,15 +83,15 @@ When a wrapper composes another size-aware base component, **forward** the size,
 
 ```tsx
 // ❌ Pinning blocks the resolution chain — the consumer's
-//    <UIProvider button={{ defaultSize: 'sm' }}> never reaches BaseButton.
-<BaseButton size="xs" {...props} />
+//    <UIProvider button={{ defaultSize: 'default' }}> never reaches BaseButton.
+<BaseButton size="small" {...props} />
 
 // ✅ Forward the resolved size; BaseButton applies its own resolution.
-const resolvedSize = sizeProp ?? 'xs';
+const resolvedSize = sizeProp ?? 'small';
 <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 size space. Still forward.
+If the wrapper genuinely needs a narrower size space, prefer the shared component scale (`'small' | 'default'`) and **map** it to the inner component's size space. Still forward.
 
 ## Slice-scoped subscriptions
 
@@ -114,7 +113,7 @@ Without the `<UIProvider>` wrapper at all, the component should still fall back
 
 ## Reference implementations
 
-- [`base/badge/badge.tsx`](../../../../../src/components/base/badge/badge.tsx) — `useBadgeConfig` consumed straightforwardly
-- [`base/buttons/base-button.tsx`](../../../../../src/components/base/buttons/base-button.tsx) — chain for both `defaultSize` and `defaultButtonStyle`
+- [`base/forms/form-sizing.ts`](../../../../../src/components/base/forms/form-sizing.ts) — shared control scale classes
+- [`base/buttons/base-button.tsx`](../../../../../src/components/base/buttons/base-button.tsx) — button scale follows `forms.defaultControlSize`; style follows `button.defaultButtonStyle`
 - [`features/filters/hooks/use-async-options.ts`](../../../../../src/components/features/filters/hooks/use-async-options.ts) — chain inside a hook (`useFiltersConfig` for `debounceMs` and `defaultPageSize`)
 - [`features/loaders/spinner.tsx`](../../../../../src/components/features/loaders/spinner.tsx) — chain for variant selection

package/.agents/skills/component-library-rules/references/visual-eval.md

@@ -10,7 +10,7 @@ Any change observable in the browser preview:
 - Restyled component (className, density, spacing, color)
 - Refactored typography (Text/Heading)
 - New preview page or section
-- Changes to CSS tokens in `src/css/themes/default.css` or `src/css/defaults.css`
+- Changes to CSS tokens in `src/css/themes/shadcn.default.css` or `src/css/tokens/*`
 
 When the change is purely structural (types, refactors that pass tsc, hooks with no UI surface), skip this — but say so explicitly rather than silently dropping the check.