admin-ui-starter-kit 0.4.5 → 0.6.1

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';
     /* … */
 }
 ```

package/.agents/skills/component-library-rules/references/components/INDEX.json

@@ -1,59 +1,68 @@
 [
   {"id":"base/accordion","title":"Accordion","description":"Two tiers — pass-through compound parts (Accordion / AccordionItem / AccordionTrigger / AccordionContent) for full control, or SmartAccordion for the canonical icon + title + optional badge + body admin pattern.","layer":"base","family":"Display","tags":["base","display","accordion","tiers","pass","through","compound"],"sourcePath":"src/components/base/accordion","publicImport":"admin-ui-starter-kit/base/accordion","examples":["Default","VariantCard","VariantBordered","VariantFlat","IconStyleMedallion","IconStyleInline","IconStyleNone","MultipleOpen","WithBadgeAndDisabled","CompoundApi","RealisticFAQ"],"doc":"./base__accordion.md"},
   {"id":"base/alert","title":"Alert","description":"Semantic notice primitive with icon, title, description, and responsive action regions.","layer":"base","family":"Display","tags":["base","display","alert","semantic","notice","primitive","icon"],"sourcePath":"src/components/base/display/alert","publicImport":"admin-ui-starter-kit/base/display","examples":["AlertVariants","AlertWithActions","InverseAlert","StatusRoleAlert"],"doc":"./base__alert.md"},
+  {"id":"base/avatar","title":"Avatar","description":"Avatar, fallback initials, and stacked avatars for compact identity surfaces.","layer":"base","family":"Display","tags":["base","display","avatar","fallback","initials","stacked","avatars"],"sourcePath":"src/components/base/display/avatar","publicImport":"admin-ui-starter-kit/base/display","examples":["AvatarSizes","StackedAvatarsExample","RealisticUserCard"],"doc":"./base__avatar.md"},
   {"id":"base/badge","title":"Badge","description":"Status pills and chips for tags, counts, and inline state.","layer":"base","family":"Foundations","tags":["base","foundations","badge","status","pills","chips","tags"],"sourcePath":"src/components/base/badge","publicImport":"admin-ui-starter-kit/base/badge","examples":["Default","Variants","WithDot"],"doc":"./base__badge.md"},
-  {"id":"base/buttons","title":"Buttons","description":"The base button family — BaseButton (variant × style × size), the higher-level Button (loader / tooltip / link wrapper), and specialty buttons (Google, Shopify, Text, PageAction).","layer":"base","family":"Foundations","tags":["base","foundations","buttons","button","family","basebutton","variant"],"sourcePath":"src/components/base/buttons","publicImport":"admin-ui-starter-kit/base/buttons","examples":["Default","AllVariantsSolid","AllVariantsOutline","AllVariantsGhost","VariantStyleMatrix","Sizes","IconOnlySizes","WithIconLeft","WithIconRight","StateDisabled","StateFullWidth","ButtonComboFeatures","LoaderButtonStates","LoaderButtonInteractive","TooltipButtonExample","GoogleButtonExample","ShopifyButtonExample","TextButtonSizes","PageActionButtonVariants","PageActionButtonSizes","RealisticToolbar"],"doc":"./base__buttons.md"},
-  {"id":"base/cards","title":"Cards (SmartCard)","description":"The composed card primitive — header (icon, title, suffix, slots), optional alert, expandable body, footer text or slot, and three surface chromes.","layer":"base","family":"Foundations","tags":["base","foundations","cards","smartcard","composed","card","primitive"],"sourcePath":"src/components/base/cards","publicImport":"admin-ui-starter-kit/base/cards","examples":["Default","WithIconTooltipFooter","WithActions","AlertVariants","PaddingSizes","SurfaceVariants","HeaderSlots","HeaderAndFooterDividers","ExpandableUncontrolled","ExpandableCustomLabels","Skeleton","MetricKPICard","NotificationCard","PrimitiveComposition","StatRowClickable"],"doc":"./base__cards.md"},
+  {"id":"base/buttons","title":"Buttons","description":"The base button family — BaseButton (semantic variants, style, package scale), the higher-level Button (loader / tooltip / link wrapper), and specialty buttons (Google, Shopify, Text, PageAction).","layer":"base","family":"Foundations","tags":["base","foundations","buttons","button","family","basebutton","semantic"],"sourcePath":"src/components/base/buttons","publicImport":"admin-ui-starter-kit/base/buttons","examples":["Default","AllVariantsSolid","AllVariantsOutline","AllVariantsGhost","VariantStyleMatrix","Sizes","IconOnlySizes","WithIconLeft","WithIconRight","StateDisabled","StateFullWidth","ButtonComboFeatures","LoaderButtonStates","LoaderButtonInteractive","TooltipButtonExample","GoogleButtonExample","ShopifyButtonExample","TextButtonSizes","PageActionButtonVariants","PageActionButtonSizes","RealisticToolbar"],"doc":"./base__buttons.md"},
+  {"id":"base/cards","title":"Cards (SmartCard)","description":"The composed card primitive — header (icon, title, suffix, slots), optional alert, expandable body, footer text or slot, and calibrated card spacing.","layer":"base","family":"Foundations","tags":["base","foundations","cards","smartcard","composed","card","primitive"],"sourcePath":"src/components/base/cards","publicImport":"admin-ui-starter-kit/base/cards","examples":["Default","WithIconTooltipFooter","WithActions","AlertVariants","PaddingSizes","SurfaceVariants","FrameMode","HeaderSlots","HeaderAndFooterDividers","ExpandableUncontrolled","ExpandableCustomLabels","Skeleton","MetricKPICard","NotificationCard","PrimitiveComposition","StatRowClickable"],"doc":"./base__cards.md"},
   {"id":"base/carousel","title":"Carousel","description":"Embla-backed carousel with keyboard navigation, orientation support, plugins, and base Button controls.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","carousel","embla","backed","keyboard","orientation"],"sourcePath":"src/components/base/carousel","publicImport":"admin-ui-starter-kit/base/carousel","examples":["ProductCarousel","InsideControlsCarousel","GalleryCarousel","ProductGridGallery","TopNavigationCarousel","ResponsiveCarousel","VerticalCarousel","LocalizedControls"],"doc":"./base__carousel.md"},
   {"id":"base/chart","title":"Chart","description":"Token-aware Recharts helpers plus a composed ChartCard for admin analytics surfaces.","layer":"base","family":"Display","tags":["base","display","chart","token","aware","recharts","helpers"],"sourcePath":"src/components/base/display/chart","publicImport":"admin-ui-starter-kit/base/display/chart","examples":["BarChartCard","AreaChartCard","LineChartCard","DonutChartCard","RadialChartCard","MixedSeriesChartCard"],"doc":"./base__chart.md"},
-  {"id":"base/combobox","title":"Combobox","description":"EnhancedCombobox and EnhancedComboboxMultiple — searchable, optionally grouped, with apply / close-on-select behaviours, async fetchers, custom rendering, and form integration.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","combobox","enhancedcombobox","enhancedcomboboxmultiple","searchable","optionally"],"sourcePath":"src/components/base/combobox","publicImport":"admin-ui-starter-kit/base/combobox","examples":["Default","SingleSelect","SingleHighlightMatch","SingleCreatable","MultipleSelect","MultipleApplyButton","MultipleCloseOnSelect","MultipleGrouped","GroupedTeamByRole","AsyncCustomers","AsyncDebouncedSearch","AsyncWithLoadMore","CustomItemRendering","CustomGroupLabels","SizeSm","SizeMd","SizeLg","Disabled","Invalid","MinSearchLength","RealisticCustomerPicker","FormFieldIntegration"],"doc":"./base__combobox.md"},
+  {"id":"base/combobox","title":"Combobox","description":"EnhancedCombobox and EnhancedComboboxMultiple — searchable, optionally grouped, with apply / close-on-select behaviours, async fetchers, custom rendering, and form integration.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","combobox","enhancedcombobox","enhancedcomboboxmultiple","searchable","optionally"],"sourcePath":"src/components/base/combobox","publicImport":"admin-ui-starter-kit/base/combobox","examples":["Default","SingleSelect","SingleHighlightMatch","SingleCreatable","MultipleSelect","MultipleApplyButton","MultipleCloseOnSelect","MultipleGrouped","GroupedTeamByRole","AsyncCustomers","AsyncResourceCustomerPicker","AsyncDebouncedSearch","AsyncWithLoadMore","CustomItemRendering","CustomGroupLabels","CssVariableScale","Disabled","Invalid","MinSearchLength","RealisticCustomerPicker","FormFieldIntegration"],"doc":"./base__combobox.md"},
   {"id":"base/copyable","title":"Copyable","description":"Click-to-copy inline span with hover affordance and toast feedback.","layer":"base","family":"Display","tags":["base","display","copyable","click","copy","inline","span"],"sourcePath":"src/components/base/copyable","publicImport":"admin-ui-starter-kit/base/copyable","examples":["Default","Mono","MonoTruncate","CustomDisplayValue","CustomToastMessage","RealisticOrderRow","CustomerListWithCopyableEmails"],"doc":"./base__copyable.md"},
+  {"id":"base/css-variables","title":"CSS Variables","description":"Token reference for the compact structural contract that controls typography, spacing, density, controls, rows, surfaces, media, and shell dimensions.","layer":"base","family":"Foundations","tags":["base","foundations","*","css","variables","token","reference"],"sourcePath":"src/css/themes/shadcn.default.css + src/css/tokens/*","publicImport":"","examples":["ScalePreview","RuntimeOverrideDemo","VariableExplorer"],"doc":"./base__css-variables.md"},
   {"id":"base/currency","title":"Currency","description":"MoneyDisplay and CurrencyPairPreview — locale-aware, dual-pricing-aware money rendering driven by useCurrency() / UIProvider config.","layer":"base","family":"Display","tags":["base","display","currency","moneydisplay","currencypairpreview","locale","aware"],"sourcePath":"src/components/base/currency","publicImport":"admin-ui-starter-kit/base/currency","examples":["Default","Sizes","MultipleCurrencies","EmptyState","PairStackedEmphasisVariants","PairInlineEmphasisVariants","PairMinimalVariant","CurrencyPairPreviewExample","ProviderConfigDualPricing","RealisticOrdersList"],"doc":"./base__currency.md"},
   {"id":"base/date-pickers","title":"Date pickers","description":"DatePicker (single / range / multiple) and MonthYearPicker — popover-based, locale-aware, with optional year dropdown and time input.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","date-pickers","date","pickers","datepicker","single"],"sourcePath":"src/components/base/date-pickers","publicImport":"admin-ui-starter-kit/base/date-pickers","examples":["Default","ModeSingle","ModeRange","ModeMultiple","WithYearDropdown","ButtonStyles","MonthYearPickerExample","DateRangePickerLegacy","WithTimeInput","RealisticDateFilter"],"doc":"./base__date-pickers.md"},
-  {"id":"base/display","title":"Display","description":"The display layer — Avatar, IconBadge, InlineStat, Tooltip, Separator, NotificationBanner, BooleanIndicator, ShowIf, ThrottleAlert, VisuallyHidden, PlaceholderPattern.","layer":"base","family":"Display","tags":["base","display","layer","avatar","iconbadge","inlinestat"],"sourcePath":"src/components/base/display","publicImport":"admin-ui-starter-kit/base/display","examples":["NotificationBannerVariants","AvatarSizes","StackedAvatarsExample","IconBadgeTones","IconBadgeShapes","IconBadgeSizes","InlineStatLayouts","SeparatorExample","TooltipExample","BooleanIndicatorExample","ShowIfExample","ThrottleAlertExample","VisuallyHiddenExample","PlaceholderPatternExample","AlertExample","ProgressExample","SkeletonExample","CollapsibleExample","DialogExample","DateBlockExample","MoneyDisplayExample","QRCodeExample","RealisticUserCard"],"doc":"./base__display.md"},
-  {"id":"base/empty-state","title":"Empty state","description":"Adaptive zero-data surface. Wrap with the right illustration per resource — products, users, search results, inbox. Slots for media / actions / footer; consumer overrides every string.","layer":"base","family":"Display","tags":["base","display","empty-state","empty","state","adaptive","zero"],"sourcePath":"src/components/base/display/empty-state","publicImport":"admin-ui-starter-kit/base/display","examples":["Default","NoProductsWithActions","NoTeamMembers","NoSearchResults","InboxZero","PaddingCompact","PaddingBase","PaddingLoose","DashedBorderDropZone","StringsPropLocalisation","RenderPropCustomMedia"],"doc":"./base__empty-state.md"},
+  {"id":"base/display-utilities","title":"Display utilities","description":"Narrow display helpers only: separator, banners, boolean indicators, conditionals, progress, skeleton, and utility wrappers.","layer":"base","family":"Display","tags":["base","display","utilities","narrow","helpers","only"],"sourcePath":"src/components/base/display","publicImport":"admin-ui-starter-kit/base/display","examples":["NotificationBannerVariants","SeparatorExample","BooleanIndicatorExample","ShowIfExample","ThrottleAlertExample","VisuallyHiddenExample","PlaceholderPatternExample","AlertExample","ProgressExample","SkeletonExample","CollapsibleExample","DialogExample","DateBlockExample","MoneyDisplayExample","QRCodeExample"],"doc":"./base__display-utilities.md"},
   {"id":"base/event-calendar","title":"Event calendar","description":"Month view with categories, filtering, navigation rules, custom event rendering, and three day-heading variants.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","event-calendar","event","calendar","month","view"],"sourcePath":"src/components/base/event-calendar","publicImport":"admin-ui-starter-kit/base/event-calendar","examples":["Default","RangeModeMonthYearCompactMonthYearJump","NavigationLimitsDisabledDates","FilterEventRenderEventCustomEventRendering","DayHeadingVariantTinted","DayHeadingVariantBordered","DayHeadingVariantAccent","WithCustomStringsBG"],"doc":"./base__event-calendar.md"},
-  {"id":"base/forms","title":"Forms","description":"The full form scope — FormField wrapper plus every field component exported from base/forms/fields: text inputs, numeric, selects, toggles, choice groups, date/time, repeaters, localized fields, and uploads.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","full","form","scope","formfield"],"sourcePath":"src/components/base/forms","publicImport":"admin-ui-starter-kit/base/forms","examples":["BasicField","WithError","WithHelperText","InputBasic","InputWithIcons","PasswordInputExample","SlugFieldExample","InputWithAddons","InputClearableLoading","InputCharacterCount","TextareaExample","DecimalInputExample","PercentageInputExample","CurrencyInputExample","MoneyInputExample","WeightInputExample","DimensionsInputExample","SelectExample","RichSelectExample","RoundingModeSelectExample","SwitchExample","CheckboxExample","ToggleFieldExample","SwitchCardExample","PillRadioGroupExample","ListRadioGroupExample","CardRadioGroupExample","CardCheckboxGroupExample","DateTimeInputExample","TimePickerExample","SliderExample","TagsInputExample","PhoneInputExample","CoordinatesInputExample","StringRepeaterExample","ObjectRepeaterExample","KeyValueEditorExample","ListExample","LocalizedStringFieldExample","LocalizedObjectFieldExample","LocalizedStringRepeaterExample","AvatarUploadExample","DropzoneExample","WholeForm"],"doc":"./base__forms.md"},
-  {"id":"base/frame","title":"Frame","description":"Grouped panel primitive for related admin content, stacked records, and dense framed surfaces.","layer":"base","family":"Foundations","tags":["base","foundations","frame","grouped","panel","primitive","related"],"sourcePath":"src/components/base/frame","publicImport":"admin-ui-starter-kit/base/frame","examples":["DefaultFrame","StackedPanels","InverseFrame","DenseFitPanel","FrameVariantMatrix"],"doc":"./base__frame.md"},
+  {"id":"base/forms","title":"Forms","description":"The full form scope — FormField wrapper plus every field component exported from base/forms/fields: text inputs, numeric, selects, toggles, choice groups, date/time, repeaters, localized fields, and uploads.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","full","form","scope","formfield"],"sourcePath":"src/components/base/forms","publicImport":"admin-ui-starter-kit/base/forms","examples":["BasicField","WithError","WithHelperText","WorkflowChrome","InputBasic","InputWithIcons","PasswordInputExample","SlugFieldExample","InputWithAddons","InputClearableLoading","InputCharacterCount","TextareaExample","DecimalInputExample","PercentageInputExample","CurrencyInputExample","MoneyInputExample","WeightInputExample","DimensionsInputExample","SelectExample","RichSelectExample","RoundingModeSelectExample","SwitchExample","CheckboxExample","ToggleFieldExample","SwitchCardExample","PillRadioGroupExample","ListRadioGroupExample","CardRadioGroupExample","CardCheckboxGroupExample","DateTimeInputExample","TimePickerExample","SliderExample","TagsInputExample","PhoneInputExample","CoordinatesInputExample","StringRepeaterExample","ObjectRepeaterExample","KeyValueEditorExample","ListExample","LocalizedStringFieldExample","LocalizedObjectFieldExample","LocalizedStringRepeaterExample","AvatarUploadExample","DropzoneExample","WholeForm"],"doc":"./base__forms.md"},
+  {"id":"base/icon-badge","title":"Icon badge","description":"Tokenized icon container for status, resource, and row media affordances.","layer":"base","family":"Display","tags":["base","display","icon-badge","icon","badge","tokenized","container"],"sourcePath":"src/components/base/display/icon-badge","publicImport":"admin-ui-starter-kit/base/display","examples":["IconBadgeTones","IconBadgeShapes","IconBadgeSmallDefault"],"doc":"./base__icon-badge.md"},
   {"id":"base/item","title":"Item","description":"Canonical row primitive — icon/avatar/image media, title + description content, optional actions. Use ItemGroup to compose lists.","layer":"base","family":"Foundations","tags":["base","foundations","item","canonical","row","primitive","icon"],"sourcePath":"src/components/base/item","publicImport":"admin-ui-starter-kit/base/item","examples":["Basic","Variants","PolymorphicLink"],"doc":"./base__item.md"},
   {"id":"base/map","title":"Map","description":"Leaflet-backed map primitives — Map shell, MapTileLayer, MapMarker, MapPopup. Always wrap in a fixed-height container.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","map","leaflet","backed","primitives","shell"],"sourcePath":"src/components/base/map","publicImport":"admin-ui-starter-kit/base/map","examples":["Default","MultipleMarkers","TighterZoom","CompactSize"],"doc":"./base__map.md"},
-  {"id":"base/metadata-list","title":"Metadata list","description":"Flexible label/value list for entity metadata. Three layouts (vertical grid, horizontal pills, two-column rows), per-item icons, tooltips, descriptions, and custom renderers — with first-class empty-state handling.","layer":"base","family":"","tags":["base","metadata","list","flexible","label","value"],"sourcePath":"src/components/base/display/metadata","publicImport":"admin-ui-starter-kit/base/display/metadata","examples":["APISurface","Vertical2ColumnNoIcons","VerticalSingleColumnNoIcons","RowsTwoColumnWithHairlines","RowsReceiptStyle","RowsWithIconsTooltips","SectionedMultiCard","Dense4ColumnOverview","Example3ColumnWithIcons","HorizontalPillSummary","WithTitleSeparator","EmptyStateFallbacksCustomRenderers"],"doc":"./base__metadata-list.md"},
   {"id":"base/navigation","title":"Navigation","description":"The navigation primitives — PageHeader, Breadcrumbs, ActionMenu, LanguageSwitcher, SectionNav, SideNav, AsideNavigationMenu, TabNavigationMenu, NavigationTabs, OverflowTabBar.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","primitives","pageheader","breadcrumbs","actionmenu"],"sourcePath":"src/components/base/navigation","publicImport":"admin-ui-starter-kit/base/navigation","examples":["PageHeaderExample","SectionNavSticky","BreadcrumbsSizes","ActionMenuExample","LanguageSwitcherButtons","LanguageSwitcherInline","AsideNavigationMenuExample","TabNavigationMenuExample","NavigationTabsRound","SideNavCollapsibleGroups","OverflowTabBarResponsiveWithMoreMenu"],"doc":"./base__navigation.md"},
-  {"id":"base/spinner","title":"Spinner","description":"Loading indicator with three visual variants. Pairs with content placeholders, route transitions, and Suspense fallbacks.","layer":"base","family":"","tags":["base","spinner","loading","indicator","visual","variants"],"sourcePath":"src/components/base/spinner","publicImport":"admin-ui-starter-kit/base/spinner","examples":["Default","Variants","WithLabel","CustomColour","SectionPlaceholder"],"doc":"./base__spinner.md"},
-  {"id":"base/table","title":"Table","description":"DataTable + Pagination — TanStack-React-Table-backed, with sorting, row actions, sticky header, three sizes, and three surface chromes.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","table","datatable","pagination","tanstack","react"],"sourcePath":"src/components/base/table","publicImport":"admin-ui-starter-kit/base/table","examples":["BasicDefaultSizeXsCompact","SizeSm","SizeBase","SurfaceGlassHeaderTransparentCleanOutlineNoMutedHeader","SurfaceFlatInsideSmartCardTableRendersNoChrome","SizeSmGlassExplicitCellTextScaling","WithSortingRowActions","PaginationExample","RealisticOrdersTable","CellRenderers","WithRowSelection","WithColumnVisibility","WithCustomToolbar","StickyHeaderAndFirstColumn","EmptyState"],"doc":"./base__table.md"},
+  {"id":"base/spinner","title":"Spinner","description":"Loading indicator with three visual variants. Pairs with content placeholders, route transitions, and Suspense fallbacks.","layer":"base","family":"Feedback","tags":["base","feedback","spinner","loading","indicator","visual","variants"],"sourcePath":"src/components/base/spinner","publicImport":"admin-ui-starter-kit/base/spinner","examples":["Default","Variants","WithLabel","CustomColour","SectionPlaceholder"],"doc":"./base__spinner.md"},
+  {"id":"base/table","title":"Table","description":"DataTable + Pagination — TanStack-React-Table-backed, with sorting, row actions, sticky header, calibrated table rhythm, and three surface chromes.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","table","datatable","pagination","tanstack","react"],"sourcePath":"src/components/base/table","publicImport":"admin-ui-starter-kit/base/table","examples":["BasicDefault","ComfortableTable","SurfaceGlassHeaderTransparentCleanOutlineNoMutedHeader","SurfaceFlatInsideSmartCardTableRendersNoChrome","WithSortingRowActions","PaginationExample","RealisticOrdersTable","FilteredTabbedOrdersTable","CellRenderers","IndexTableCells","WithRowSelection","WithColumnVisibility","WithCustomToolbar","DataViewChrome","StickyHeaderAndFirstColumn","EmptyState"],"doc":"./base__table.md"},
+  {"id":"base/tooltip","title":"Tooltip","description":"Tooltip provider, trigger, and content wrappers for short contextual help.","layer":"base","family":"Display","tags":["base","display","tooltip","provider","trigger","content","wrappers"],"sourcePath":"src/components/base/display/tooltip","publicImport":"admin-ui-starter-kit/base/display","examples":["TooltipExample"],"doc":"./base__tooltip.md"},
   {"id":"base/typography","title":"Typography","description":"Heading, Text, Label, and TextLink — the four typography primitives every higher layer composes from.","layer":"base","family":"Foundations","tags":["base","foundations","typography","heading","text","label","textlink"],"sourcePath":"src/components/typography","publicImport":"admin-ui-starter-kit/typography","examples":["HeadingTags","HeadingWithSubHeading","TextSizes","TextTypes","TextWeights","TextLineHeights","TextAlignment","TextContentAndHTML","TextTags","LabelExample","TextLinkVariants","TextLinkSizes","HighLightExample","UnderlineExample","DangerousHTMLExample","RealisticArticle"],"doc":"./base__typography.md"},
   {"id":"base/upload-tray","title":"Upload tray","description":"Drag-drop area + per-file progress rows + summary toolbar. Composes Dropzone and UploadProgressList. Framework-agnostic — the consumer drives the actual transfer.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","fields","upload","tray","drag","drop"],"sourcePath":"src/components/base/forms/fields","publicImport":"admin-ui-starter-kit/base/forms","examples":["Default","EmptyDropzoneOnly","MixedItemStates","LiveSimulatedUpload","LocalisedFrench"],"doc":"./base__upload-tray.md"},
   {"id":"common/brand","title":"Common · Brand","description":"Inline Logo + AppLogo variants used by the preview shell.","layer":"common","family":"Branding","tags":["common","branding","_brand","brand","inline","logo","applogo"],"sourcePath":"src/preview/_brand","publicImport":"","examples":["LogoExample","AppLogoSizes","AppLogoVariants"],"doc":"./common__brand.md"},
-  {"id":"composed/admin","title":"Composed · Admin","description":"Team list, permissions, conversations, settings, inventory.","layer":"composed","family":"Admin","tags":["composed","admin","team","list","permissions","conversations"],"sourcePath":"src/components/composed/admin","publicImport":"admin-ui-starter-kit/composed/admin","examples":["TeamMembers","RolePermissions","RecentConversations","SettingsToggles","InventoryLevel"],"doc":"./composed__admin.md"},
-  {"id":"composed/ai","title":"Composed · AI","description":"Summary block + classification panel.","layer":"composed","family":"AI","tags":["composed","ai","summary","block","classification","panel"],"sourcePath":"src/components/composed/ai","publicImport":"admin-ui-starter-kit/composed/ai","examples":["AISummary","AIClassification"],"doc":"./composed__ai.md"},
+  {"id":"composed/admin","title":"Composed · Admin","description":"Team list, permissions, conversations, settings, inventory.","layer":"composed","family":"Admin","tags":["composed","admin","team","list","permissions","conversations"],"sourcePath":"src/components/composed/admin","publicImport":"admin-ui-starter-kit/composed/admin","examples":["TeamMembers","RolePermissions","RecentConversations","SettingsToggles","InventoryLevel","ActionSurfaces","TokenManager"],"doc":"./composed__admin.md"},
+  {"id":"composed/ai","title":"Composed · AI","description":"Summary block, classification panel, confidence card, prompt suggestions, usage card, message bubble, tool call, citation, and feedback.","layer":"composed","family":"AI","tags":["composed","ai","summary","block","classification","panel"],"sourcePath":"src/components/composed/ai","publicImport":"admin-ui-starter-kit/composed/ai","examples":["AISummary","AIClassification"],"doc":"./composed__ai.md"},
   {"id":"composed/ai-elements","title":"Composed · AI (elements)","description":"Standalone surfaces ported from elements.ai-sdk.dev: shimmer, code-block, agent, package-info, reasoning, chain-of-thought, sources, inline-citation, task, artifact, file-tree, confirmation, attachment.","layer":"composed","family":"AI","tags":["composed","ai","elements","standalone","surfaces","ported"],"sourcePath":"src/components/composed/ai","publicImport":"admin-ui-starter-kit/composed/ai","examples":["Counter","AiShimmerExample","AiAgentExample","AiCodeBlockExample","AiAttachmentExample","AiInlineCitationExample","AiSourcesExample","AiReasoningExample","AiChainOfThoughtExample","AiTaskExample","AiArtifactExample","AiFileTreeExample","AiPackageInfoExample","AiConfirmationExample"],"doc":"./composed__ai-elements.md"},
-  {"id":"composed/ai-new","title":"Composed · AI (extras)","description":"Confidence dial, prompt suggestions, token usage card, message bubble, tool call, citation, feedback.","layer":"composed","family":"AI","tags":["composed","ai","extras","confidence","dial","prompt"],"sourcePath":"src/components/composed/ai","publicImport":"admin-ui-starter-kit/composed/ai","examples":["AiConfidenceCardExample","AiPromptSuggestionsExample","AiTokenUsageCardExample","AiMessageBubbleExample","AiToolCallExample","AiCitationExample","AiFeedbackExample"],"doc":"./composed__ai-new.md"},
   {"id":"composed/api-key-list","title":"Composed · Admin · API key list","description":"Collapsible section with per-row dropdown menu (Copy / Delete) and an optional Add action in the header. Generic enough for any 'named secret list' — service tokens, webhook URLs, deployment hooks. Composes base/cards + base/display/collapsible + base/navigation/ActionMenu + base/copyable.","layer":"composed","family":"Admin","tags":["composed","admin","api","key","list","collapsible"],"sourcePath":"src/components/composed/admin","publicImport":"admin-ui-starter-kit/composed/admin","examples":["DefaultVisibleSecretsCallbacksForAddDelete","MaskedSecretsStripeStyle","EmptyState","LocalizedStrings"],"doc":"./composed__api-key-list.md"},
-  {"id":"composed/commerce","title":"Composed · Commerce","description":"Bookings, loyalty, discount stacks, shipment tracking.","layer":"composed","family":"Commerce","tags":["composed","commerce","bookings","loyalty","discount","stacks"],"sourcePath":"src/components/composed/commerce","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["UpcomingBookings","LoyaltyPoints","DiscountStack","ShipmentTracking"],"doc":"./composed__commerce.md"},
-  {"id":"composed/commerce-extras","title":"Composed · Commerce (extras)","description":"Cart, coupon, order status, payment, tax breakdown, subscription, refund, address, voucher.","layer":"composed","family":"Commerce","tags":["composed","commerce","extras","cart","coupon","order"],"sourcePath":"src/components/composed/commerce","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["CartSummaryCardExample","CouponInputCardEmptyApplied","OrderStatusCardExample","PaymentMethodCardExample","TaxBreakdownCardExample","SubscriptionSummaryCardExample","RefundStatusCardExample","AddressCardExample","VoucherEntryCardExample"],"doc":"./composed__commerce-extras.md"},
+  {"id":"composed/commerce","title":"Composed · Commerce","description":"Bookings, loyalty, discount stacks, shipment tracking, cart, coupons, payment, tax, subscription, refund, address, and voucher surfaces.","layer":"composed","family":"Commerce","tags":["composed","commerce","bookings","loyalty","discount","stacks"],"sourcePath":"src/components/composed/commerce","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["UpcomingBookings","LoyaltyPoints","DiscountStack","ShipmentTracking"],"doc":"./composed__commerce.md"},
   {"id":"composed/contact-card","title":"Composed · Contact card","description":"ContactCard — name, role, email, phone, location, badge.","layer":"composed","family":"Cards","tags":["composed","cards","contact-card","contact","card","contactcard","name"],"sourcePath":"src/components/composed/cards/contact-card","publicImport":"admin-ui-starter-kit/composed/cards","examples":["WithAllFields","WithInitialsOnly","Minimal","DifferentBadgeVariants"],"doc":"./composed__contact-card.md"},
   {"id":"composed/course-card","title":"Composed · Course card","description":"Operational session cards for bookings, courses, and guided experiences.","layer":"composed","family":"Cards","tags":["composed","cards","course-card","course","card","operational","session"],"sourcePath":"src/components/composed/cards/course-card","publicImport":"admin-ui-starter-kit/composed/cards","examples":["DefaultSession","FeaturedSession","CompactList"],"doc":"./composed__course-card.md"},
   {"id":"composed/dark-surfaces","title":"Composed · Dark surfaces","description":"Dark-wrapped components — payment, receipt, info panel, order items, outstanding balance.","layer":"composed","family":"Surfaces","tags":["composed","surfaces","dark-surfaces","dark","wrapped","components","payment"],"sourcePath":"src/components/composed/dark-surfaces","publicImport":"admin-ui-starter-kit/composed/dark-surfaces","examples":["PaymentConfirmation","BookingReceipt","InfoPanel","OrderItems","OutstandingBalance"],"doc":"./composed__dark-surfaces.md"},
   {"id":"composed/dense-info","title":"Composed · Dense info cards","description":"Five layout variants — dashboard, classification, financial, project, score.","layer":"composed","family":"Data display","tags":["composed","data","display","dense-info-card","dense","info","cards","five"],"sourcePath":"src/components/composed/data-display/dense-info-card","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["Dashboard","ScoreCard","Classification","Financial","ProjectCards"],"doc":"./composed__dense-info.md"},
+  {"id":"composed/empty-state","title":"Empty state","description":"Adaptive zero-data surface. Wrap with the right illustration per resource — products, users, search results, inbox. Slots for media / actions / footer; consumer overrides every string.","layer":"base","family":"Data display","tags":["base","data","display","empty-state","empty","state","adaptive","zero"],"sourcePath":"src/components/composed/data-display/empty-state","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["Default","NoProductsWithActions","NoTeamMembers","NoSearchResults","InboxZero","PaddingCompact","PaddingBase","PaddingLoose","DashedBorderDropZone","StringsPropLocalisation","RenderPropCustomMedia"],"doc":"./composed__empty-state.md"},
   {"id":"composed/feature-announcement","title":"Composed · Feature announcement","description":"Highlight a new feature with tags and an action.","layer":"composed","family":"Cards","tags":["composed","cards","feature-announcement","feature","announcement","highlight","new"],"sourcePath":"src/components/composed/cards/feature-announcement","publicImport":"admin-ui-starter-kit/composed/cards","examples":["WithIconTagsAction"],"doc":"./composed__feature-announcement.md"},
   {"id":"composed/giftcard-cards","title":"Composed · Giftcard cards","description":"Five visual variants — gradient, compact, minimal, dark, illustrated.","layer":"composed","family":"Cards","tags":["composed","cards","giftcard-card","giftcard","five","visual","variants"],"sourcePath":"src/components/composed/cards/giftcard-card","publicImport":"admin-ui-starter-kit/composed/cards","examples":["GradientDefault","Minimal","Dark","Illustrated","CompactActiveExpired"],"doc":"./composed__giftcard-cards.md"},
   {"id":"composed/gradient-card","title":"Composed · Gradient card","description":"Vivid gradient card with optional pattern, badge, alert, action.","layer":"composed","family":"Cards","tags":["composed","cards","gradient-card","gradient","card","vivid","optional"],"sourcePath":"src/components/composed/cards/gradient-card","publicImport":"admin-ui-starter-kit/composed/cards","examples":["HeroCardWithAction","CompactAllGradients","HeroVariants"],"doc":"./composed__gradient-card.md"},
+  {"id":"composed/inline-stat","title":"Inline stat","description":"Inline label/value pairs for counters, totals, and compact card rows. Use MetadataList for entity detail fields.","layer":"base","family":"Data display","tags":["base","data","display","inline-stat","inline","stat","label","value"],"sourcePath":"src/components/composed/data-display/inline-stat","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["InlineStatLayouts"],"doc":"./composed__inline-stat.md"},
   {"id":"composed/invoice-header","title":"Composed · Invoice header","description":"Top of an invoice — number, status, parties, amount.","layer":"composed","family":"Data display","tags":["composed","data","display","invoice-header","invoice","header","top","number"],"sourcePath":"src/components/composed/data-display/invoice-header","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["Paid","Overdue"],"doc":"./composed__invoice-header.md"},
   {"id":"composed/invoice-items","title":"Composed · Invoice items","description":"Table, compact, detailed layouts with subtotal/tax/discount/total.","layer":"composed","family":"Data display","tags":["composed","data","display","invoice-items","invoice","items","table","compact"],"sourcePath":"src/components/composed/data-display/invoice-items","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["Table","Compact","Detailed"],"doc":"./composed__invoice-items.md"},
   {"id":"composed/invoice-mini","title":"Composed · Invoice mini","description":"Compact invoice tile — paid / pending / overdue.","layer":"composed","family":"Data display","tags":["composed","data","display","invoice-mini","invoice","mini","compact","tile"],"sourcePath":"src/components/composed/data-display/invoice-mini","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["Statuses"],"doc":"./composed__invoice-mini.md"},
   {"id":"composed/invoice-table","title":"Composed · Invoice table","description":"Line items with qty / price / total.","layer":"composed","family":"Data display","tags":["composed","data","display","invoice-table","invoice","table","line","items"],"sourcePath":"src/components/composed/data-display/invoice-table","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["Default","WithTaxRate"],"doc":"./composed__invoice-table.md"},
+  {"id":"composed/metadata-list","title":"Metadata list","description":"Flexible label/value list for entity metadata. Three layouts (vertical grid, horizontal pills, two-column rows), per-item icons, tooltips, descriptions, and custom renderers — with first-class empty-state handling.","layer":"base","family":"Data display","tags":["base","data","display","metadata","list","flexible","label","value"],"sourcePath":"src/components/composed/data-display/metadata","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["APISurface","Vertical2ColumnNoIcons","VerticalSingleColumnNoIcons","RowsTwoColumnWithHairlines","RowsReceiptStyle","RowsWithIconsTooltips","SectionedMultiCard","Dense4ColumnOverview","Vertical3ColumnWithIcons","HorizontalPillSummary","WithTitleSeparator","EmptyStateFallbacksCustomRenderers"],"doc":"./composed__metadata-list.md"},
   {"id":"composed/navigation","title":"Composed · Navigation & boards","description":"Kanban, tab switcher, time ruler, vendor performance, experience activity.","layer":"composed","family":"Navigation","tags":["composed","navigation","boards","kanban","tab","switcher"],"sourcePath":"src/components/composed/navigation","publicImport":"admin-ui-starter-kit/composed/navigation","examples":["KanbanMicroBoardExample","TabSwitcherCardExample","TimeDistributionRulerExample","VendorPerformance","ExperienceActivity"],"doc":"./composed__navigation.md"},
   {"id":"composed/navigation-extras","title":"Composed · Navigation (extras)","description":"BreadcrumbProgress wizard + CategoryNavCard sidebar.","layer":"composed","family":"Navigation","tags":["composed","navigation","extras","breadcrumbprogress","wizard","categorynavcard"],"sourcePath":"src/components/composed/navigation","publicImport":"admin-ui-starter-kit/composed/navigation","examples":["BreadcrumbProgressExample","CategoryNavCardExample"],"doc":"./composed__navigation-extras.md"},
   {"id":"composed/onboarding-checklist","title":"Composed · Onboarding · Checklist","description":"Step-list accordion with completed / in-progress / pending status indicators. Auto-opens the next non-completed step. Strings + status ARIA fully overridable. Composes base/accordion.","layer":"composed","family":"Onboarding","tags":["composed","onboarding","checklist","step","list","accordion"],"sourcePath":"src/components/composed/onboarding","publicImport":"admin-ui-starter-kit/composed/onboarding","examples":["BorderedDefaultPointOfSaleOnboarding","CardVariantWorkspaceSetupControlled","FlatVariantMinimal"],"doc":"./composed__onboarding-checklist.md"},
+  {"id":"composed/resource-selector-card","title":"Composed · Resource selector card","description":"Selected-resource card for dialogs, forms, and show pages. The app owns picking, fetching, and routing.","layer":"composed","family":"Data display","tags":["composed","data","display","resource-selector-card.tsx","resource","selector","card","selected"],"sourcePath":"src/components/composed/data-display/resource-selector-card.tsx","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["SelectedResource","EmptyResource"],"doc":"./composed__resource-selector-card.md"},
   {"id":"composed/timelines","title":"Composed · Timelines","description":"Read-only tracking timelines — steps, order, payment, activity stream, release changelog, project milestones. For interactive activity (segments, mass-config, resource registry, callbacks) see Features → Activity feed.","layer":"composed","family":"Timelines","tags":["composed","timelines","read","only","tracking","steps"],"sourcePath":"src/components/composed/timelines","publicImport":"admin-ui-starter-kit/composed/timelines","examples":["StepsVertical","StepsHorizontalExample","OrderTimeline","PaymentTimeline","ActivityStreamReadOnlyTracking","Changelog","Milestones"],"doc":"./composed__timelines.md"},
   {"id":"composed/vendor-profile","title":"Composed · Vendor profile","description":"VendorProfileCard with metrics, stats and actions.","layer":"composed","family":"Cards","tags":["composed","cards","vendor-profile","vendor","profile","vendorprofilecard","metrics"],"sourcePath":"src/components/composed/cards/vendor-profile","publicImport":"admin-ui-starter-kit/composed/cards","examples":["WithEverything","Minimal"],"doc":"./composed__vendor-profile.md"},
+  {"id":"docs/design-system-consistency","title":"Design system consistency guide","description":"The operating manual for keeping the package cohesive: goals, ownership, token rules, drift detection, and browser-quality review.","layer":"docs","family":"Start here","tags":["docs","start","here","preview","design","system","consistency","guide"],"sourcePath":"src/components + src/css + src/preview","publicImport":"","examples":[],"doc":"./docs__design-system-consistency.md"},
+  {"id":"docs/installation","title":"Installation","description":"Install the package, import the stylesheet, and consume exact public subpaths.","layer":"docs","family":"Start here","tags":["docs","start","here","readme.md","installation","install","package","import"],"sourcePath":"README.md","publicImport":"","examples":["InstallCommand","RequiredSteps","ImportRecipe","OptionalPeers","MaintainerChecks","NextLinks"],"doc":"./docs__installation.md"},
+  {"id":"docs/overview","title":"Overview","description":"How the starter kit is organized, how to browse it, and which contracts consumers can rely on.","layer":"docs","family":"Start here","tags":["docs","start","here","registry.tsx","overview","how","starter","kit"],"sourcePath":"src/preview/registry.tsx","publicImport":"","examples":["OverviewSnapshot","LayerMap","NavigationModel","PackageFlow","ArchitectureRule"],"doc":"./docs__overview.md"},
+  {"id":"docs/refinement-guide","title":"Refinement guide","description":"What changed in the showcase, why it matters, and how to keep polishing the package without losing the system contract.","layer":"docs","family":"Start here","tags":["docs","start","here","registry.tsx","refinement","guide","what","changed"],"sourcePath":"src/preview/PreviewApp.tsx + src/preview/registry.tsx","publicImport":"","examples":["RefinementOutcomes","RefinementGoals","ReviewLoop","AcceptanceChecklist","NextPassTargets"],"doc":"./docs__refinement-guide.md"},
+  {"id":"docs/showcase","title":"Showcase","description":"How to use this preview app as the package map, design review surface, and release verification aid.","layer":"docs","family":"Start here","tags":["docs","start","here","preview","showcase","how","app","package"],"sourcePath":"src/preview","publicImport":"","examples":["ShowcaseWorkflow","SearchTargets","RouteShortcuts","InteractionChecks"],"doc":"./docs__showcase.md"},
   {"id":"features/activities","title":"Features · Activity feed","description":"Interactive activity feed — generic, framework-agnostic, with headline segments, callbacks (actor / resource / action), strings, slots, mass event configuration, and a save/restore resource registry. For read-only tracking timelines (order, payment, changelog, milestones) see Composed → Timelines.","layer":"features","family":"Collaboration","tags":["features","collaboration","activities","activity","feed","interactive","generic"],"sourcePath":"src/components/features/activities","publicImport":"admin-ui-starter-kit/features/activities","examples":["DefaultFeed","CompactFeed","RichFeed","EventConfiguration","CustomRows","ResourceRegistry"],"doc":"./features__activities.md"},
   {"id":"features/ai-chat","title":"AI Chat","description":"Framework-agnostic AI chat surface. Ties together prompt input, conversation, message renderer, queue, and the full composed/ai/* palette (reasoning, tool calls, attachments, artifacts, confirmations).","layer":"features","family":"AI","tags":["features","ai","ai-chat","chat","framework","agnostic","surface"],"sourcePath":"src/components/features/ai-chat","publicImport":"admin-ui-starter-kit/features/ai-chat","examples":["Counter","Default","Streaming","Empty","WithSlots","Headless"],"doc":"./features__ai-chat.md"},
   {"id":"features/card","title":"Features · Card","description":"Stateful feature cards for booking/event details and shared resource assignment. Selector state, confirmation, dialog chrome, slots, render-props, and strings stay callback-driven so consumers own persistence.","layer":"features","family":"Commerce","tags":["features","commerce","card","stateful","feature","cards","booking"],"sourcePath":"src/components/features/card","publicImport":"admin-ui-starter-kit/features/card","examples":["BookingEventCard","SharedResourceSelector","EmptySharedResource"],"doc":"./features__card.md"},
   {"id":"features/comments","title":"Features · Comments","description":"Generic, framework-agnostic comments with rich-text composer (TipTap-backed), inline resource references (mentions, links, badges), attachment uploads with progress, and reactions. Every callback / registry flows as a direct prop — no provider.","layer":"features","family":"Collaboration","tags":["features","collaboration","comments","generic","framework","agnostic","rich"],"sourcePath":"src/components/features/comments","publicImport":"admin-ui-starter-kit/features/comments","examples":["APISurface","CommentsExample","ReadOnly","EmptyStateCustomStrings","CustomReferenceRendering"],"doc":"./features__comments.md"},
+  {"id":"features/data-view","title":"Features · Data view","description":"Controlled data-view chrome for tables, filters, saved views, and pagination. Consumers own fetching, query state, table data, and persistence.","layer":"features","family":"Tables","tags":["features","tables","data-view","data","view","controlled","chrome"],"sourcePath":"src/components/features/data-view","publicImport":"admin-ui-starter-kit/features/data-view","examples":["CustomerDataView","EmptyCustomerDataView"],"doc":"./features__data-view.md"},
   {"id":"features/enhanced-activities","title":"Features · Enhanced activities","description":"Shopify-style unified surface: domain events and comments under one chronological timeline. Comments render as note activities with MentionContent-powered user, booking, and order chips. Composer at the top uses the same TipTap-backed editor with the live mention trigger flow.","layer":"features","family":"Collaboration","tags":["features","collaboration","activities","enhanced","shopify","style","unified"],"sourcePath":"src/components/features/activities","publicImport":"admin-ui-starter-kit/features/activities","examples":["APISurface","ActivityTimelineComposer","CompactDensity"],"doc":"./features__enhanced-activities.md"},
   {"id":"features/event-log","title":"Features · Event log","description":"Unified, mentions-aware mixed-source log: comments + audit events + system messages + custom kinds under one chronological surface. Inline `@user` / `#booking` / `$order` triggers work in the composer; resource chips render with tone-driven Badge variants in every entry kind.","layer":"features","family":"Collaboration","tags":["features","collaboration","event-log","event","log","unified","mentions"],"sourcePath":"src/components/features/event-log","publicImport":"admin-ui-starter-kit/features/event-log","examples":["APISurface","CommentsEventsUnderOneLog","ReadOnlyTimelineNoComposer"],"doc":"./features__event-log.md"},
-  {"id":"features/filters","title":"Filters","description":"Composable filter system. Search + multi-select stay always visible; the rest collapse behind a Filters button. Provider-driven so it works with any data source.","layer":"features","family":"Search & filter","tags":["features","search","filter","filters","composable","system","multi","select"],"sourcePath":"src/components/features/filters","publicImport":"admin-ui-starter-kit/features/filters","examples":["Default"],"doc":"./features__filters.md"},
+  {"id":"features/filters","title":"Filters","description":"Composable filter system. Search + multi-select stay always visible; the rest collapse behind a Filters button. Provider-driven so it works with any data source.","layer":"features","family":"Search & filter","tags":["features","search","filter","filters","composable","system","multi","select"],"sourcePath":"src/components/features/filters","publicImport":"admin-ui-starter-kit/features/filters","examples":["Default","QueryStateHelpers"],"doc":"./features__filters.md"},
   {"id":"features/global-search","title":"GlobalSearch","description":"Async search palette with slots, render-props, and a headless useGlobalSearch hook.","layer":"features","family":"Search & filter","tags":["features","search","filter","global-search","globalsearch","async","palette","slots"],"sourcePath":"src/components/features/global-search","publicImport":"admin-ui-starter-kit/features/global-search","examples":["Default","IdleSuggestions","PopulatedResults","LoadingState","EmptyState"],"doc":"./features__global-search.md"},
   {"id":"features/kanban","title":"Features · Kanban","description":"Drag-and-drop board, generic in T. Pass `itemActions` (static array or per-item factory) for the ⋮ menu, `onItemClick` for whole-card click. Headless via `useKanban`; slots: KanbanBoard / KanbanColumn / KanbanColumnContent / KanbanItem / KanbanItemHandle / KanbanItemActions / KanbanOverlay.","layer":"features","family":"Boards","tags":["features","boards","kanban","drag","drop","board","generic"],"sourcePath":"src/components/features/kanban","publicImport":"admin-ui-starter-kit/features/kanban","examples":["RoadmapBoardWithActionsOnItemClick"],"doc":"./features__kanban.md"},
   {"id":"features/media-library","title":"Features · Media Library","description":"Framework-agnostic media picker for admin product, CMS, and campaign flows. Provides an embeddable library surface, a Dialog-backed picker wrapper, upload staging, details editing, controlled selection, async fetching, slots, render hooks, and headless state through useMediaLibrary.","layer":"features","family":"Assets","tags":["features","assets","media-library","media","library","framework","agnostic"],"sourcePath":"src/components/features/media-library","publicImport":"admin-ui-starter-kit/features/media-library","examples":["EmbeddedLibrary","ProductMediaDialog","ResourceGalleryList","ExternalResourceGallery","ConfirmOnSelectDialog","AsyncFetcherLibrary","EmptyAndErrorStates","HeadlessSelection"],"doc":"./features__media-library.md"},
@@ -69,6 +78,7 @@
   {"id":"features/metrics-stat-cards","title":"Features · Metrics · Stat cards","description":"Two stat tile flavors built from the unified `Metric` component — `accent` (dark surface + sparkline) and `colored` (segmented progress bar).","layer":"features","family":"Metrics","tags":["features","metrics","analytics","stat","cards","tile","flavors"],"sourcePath":"src/components/composed/analytics","publicImport":"admin-ui-starter-kit/composed/analytics","examples":["MetricAccent","MetricColored"],"doc":"./features__metrics-stat-cards.md"},
   {"id":"features/overlays","title":"Features · Overlays","description":"Native dialog-backed Dialog, Drawer in four directions, and AlertDialog. Same emphasis/tone system, focus management, async-confirm flow, and confirm/cancel ergonomics across all three. Callback-driven so they slot into any framework.","layer":"features","family":"Overlays","tags":["features","overlays","native","dialog","backed","drawer"],"sourcePath":"src/components/features/overlays","publicImport":"admin-ui-starter-kit/features/overlays","examples":["APISurface","DialogDefault","DialogEmphasisTones","DialogRichContent","DialogFormPattern","Drawer4Directions","AlertDialogConfirmationPatterns","BestPractices"],"doc":"./features__overlays.md"},
   {"id":"features/products","title":"Features · Products","description":"Shopify-style product editor surfaces built from standalone product feature components. Routing, forms, and persistence stay consumer-owned.","layer":"features","family":"Commerce","tags":["features","commerce","products","shopify","style","product","editor"],"sourcePath":"src/components/features/products","publicImport":"admin-ui-starter-kit/features/products","examples":["ProductEditor","OptionsAndVariants","VariantDetailsAndEditor","StandaloneActionMenus","ProductSupportRail"],"doc":"./features__products.md"},
+  {"id":"features/resource","title":"Features · Resource shells","description":"Resource index and show shells for app-owned data, actions, tabs, loading, empty, and related-record regions.","layer":"features","family":"Operations","tags":["features","operations","resource","shells","index","show","app"],"sourcePath":"src/components/features/resource","publicImport":"admin-ui-starter-kit/features/resource","examples":["ResourceIndexShellExample","ResourceShowShellExample","TabbedResourceDetails"],"doc":"./features__resource.md"},
   {"id":"features/rich-text-editor","title":"Features · Rich text editor","description":"Tiptap-backed editor with bold / italic / strike / lists / quote / undo-redo. Falls back to a non-editable preview when @tiptap/react is not bundled. Strings overridable via the `strings` prop.","layer":"features","family":"Inputs","tags":["features","inputs","rich-text-editor","rich","text","editor","tiptap"],"sourcePath":"src/components/features/rich-text-editor","publicImport":"admin-ui-starter-kit/features/rich-text-editor","examples":["ProductionWiring","Default","CompactSmallerInlineNote","EmptyPlaceholder","Disabled","StringsOverride"],"doc":"./features__rich-text-editor.md"},
   {"id":"features/schema-form","title":"Features · Schema form","description":"Schema-driven form renderer built from the package form fields. Supports one cohesive form, section cards, controlled values, validation callbacks, and render-prop overrides.","layer":"features","family":"Inputs","tags":["features","inputs","schema-form","schema","form","driven","renderer"],"sourcePath":"src/components/features/schema-form","publicImport":"admin-ui-starter-kit/features/schema-form","examples":["CohesiveForm","SectionCards","RenderPropField"],"doc":"./features__schema-form.md"},
   {"id":"features/suggestions","title":"Features · Suggestions","description":"Framework-agnostic typeahead suggestions with a drop-in combobox and a headless hook. Consumers own fetching, selected-value persistence, telemetry, and result rendering.","layer":"features","family":"Search & filter","tags":["features","search","filter","suggestions","framework","agnostic","typeahead","drop"],"sourcePath":"src/components/features/suggestions","publicImport":"admin-ui-starter-kit/features/suggestions","examples":["AccountSuggestionsCombobox","HeadlessSuggestionsState"],"doc":"./features__suggestions.md"},
@@ -76,11 +86,13 @@
   {"id":"layout/layout-app-shell","title":"Layout · App shell","description":"Standalone header-first shell with a 70px+ topbar and a sidebar/content body grid.","layer":"layout","family":"Shells","tags":["layout","shells","app-shell","app","shell","standalone","header"],"sourcePath":"src/components/layout/app-shell","publicImport":"admin-ui-starter-kit/layout/app-shell","examples":["DarkHeaderLeftSidebar","LightHeaderRightSidebar"],"doc":"./layout__layout-app-shell.md"},
   {"id":"layout/layout-auth","title":"Layout · Auth shell","description":"Framework-neutral auth card and split shells for login, register, invite, reset, magic-link, and verification pages.","layer":"layout","family":"Shells","tags":["layout","shells","auth","shell","framework","neutral","card"],"sourcePath":"src/components/layout/auth","publicImport":"admin-ui-starter-kit/layout/auth","examples":["CenteredCardAuth","LocalizedPatternCardAuth","ProviderMatrixAuth","ResetPasswordAuth","SplitAuthShell","RightSplitAuthShell","FrameworkLinkContract"],"doc":"./layout__layout-auth.md"},
   {"id":"layout/layout-containers","title":"Layout · Containers","description":"Container and Section primitives for page structure, width clamps, padding density, and semantic wrappers.","layer":"layout","family":"Building blocks","tags":["layout","building","blocks","containers","container","section","primitives","page"],"sourcePath":"src/components/layout/containers","publicImport":"admin-ui-starter-kit/layout/containers","examples":["NarrowContainer","WideContainer","BareContainer","SectionRhythm"],"doc":"./layout__layout-containers.md"},
-  {"id":"layout/layout-header","title":"Layout · Header","description":"Topbar, breadcrumbs, command search, notifications, and action slots in a realistic app-shell canvas.","layer":"layout","family":"Shells","tags":["layout","shells","header","topbar","breadcrumbs","command"],"sourcePath":"src/components/layout","publicImport":"admin-ui-starter-kit/layout","examples":["AppHeaderComposition","HeaderPartials","CustomNotificationRenderer"],"doc":"./layout__layout-header.md"},
-  {"id":"layout/layout-page","title":"Layout · Page","description":"Page shell, header partials, actions, and content regions with framework-neutral links.","layer":"layout","family":"Shells","tags":["layout","shells","page","shell","header","partials","actions"],"sourcePath":"src/components/layout/page","publicImport":"admin-ui-starter-kit/layout/page","examples":["ProductionPageShell","ComposablePartials"],"doc":"./layout__layout-page.md"},
+  {"id":"layout/layout-header","title":"Layout · Header","description":"Topbar, breadcrumbs, command search, notifications, and action slots in a realistic app-shell canvas.","layer":"layout","family":"Shells","tags":["layout","shells","header","topbar","breadcrumbs","command"],"sourcePath":"src/components/layout","publicImport":"admin-ui-starter-kit/layout","examples":["AppHeaderComposition","HeaderPartials","HeaderToolPrimitives","CustomNotificationRenderer"],"doc":"./layout__layout-header.md"},
+  {"id":"layout/layout-page","title":"Layout · Page","description":"Page shell, index scaffolds, resource show shells, header partials, actions, and content regions with framework-neutral links.","layer":"layout","family":"Shells","tags":["layout","shells","page","shell","index","scaffolds"],"sourcePath":"src/components/layout","publicImport":"admin-ui-starter-kit/layout","examples":["ProductionPageShell","ComposablePartials","ResourceShells","TabbedResourceDetails","SettingsShellExample"],"doc":"./layout__layout-page.md"},
   {"id":"layout/layout-sidebar","title":"Layout · Sidebar","description":"Full app sidebar assembly plus reusable navigation, workspace, and footer item partials.","layer":"layout","family":"Shells","tags":["layout","shells","sidebar","full","app","assembly"],"sourcePath":"src/components/layout","publicImport":"admin-ui-starter-kit/layout","examples":["AppSidebarShell","NavigationPartials","CustomRowRenderer"],"doc":"./layout__layout-sidebar.md"},
   {"id":"layout/layout-users","title":"Layout · Users & avatars","description":"User identity surfaces used by layout headers, sidebars, menus, avatar groups, and status badges.","layer":"layout","family":"Building blocks","tags":["layout","building","blocks","users","avatars","user","identity"],"sourcePath":"src/components/layout","publicImport":"admin-ui-starter-kit/layout","examples":["AvatarStates","HeaderUserMenuExample","SidebarUserMenu","CustomTriggerCustomContent"],"doc":"./layout__layout-users.md"},
   {"id":"layout/layout-workspace","title":"Layout · Workspace","description":"Nested record workspace shell with header, workflow navigation, scroll-owned body, and optional right rail.","layer":"layout","family":"Shells","tags":["layout","shells","workspace","nested","record","shell","header"],"sourcePath":"src/components/layout/workspace","publicImport":"admin-ui-starter-kit/layout/workspace","examples":["ProductRecordWorkspaceShell","WorkspaceWithoutRail"],"doc":"./layout__layout-workspace.md"},
+  {"id":"services/actions","title":"Actions service","description":"Framework-neutral action registry, lifecycle, overlay, request, guard, and feedback glue for shared admin actions.","layer":"services","family":"Runtime","tags":["services","runtime","actions","service","framework","neutral","action"],"sourcePath":"src/services/actions","publicImport":"admin-ui-starter-kit/services/actions","examples":["RuntimeMap","LifecycleFlow","RuntimeGlue","SurfaceHelpers","FormsAndState","FitChecklist","NextRoutes"],"doc":"./services__actions.md"},
+  {"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","tags":["services","hooks","reference","public","hook","import"],"sourcePath":"src/lib/ui-provider, src/components/layout/hooks, src/services/actions, src/components/features/*/hooks","publicImport":"","examples":["HookImportMatrix","HookRules","FeatureHookList","InternalHooksNotice","HookRouteShortcuts"],"doc":"./services__hooks.md"},
   {"id":"ui/alert","title":"UI · Alert","description":"shadcn alert primitive: variants, with title/description/action.","layer":"ui","family":"Feedback","tags":["ui","feedback","alert","shadcn","primitive","variants","title"],"sourcePath":"src/components/ui/alert","publicImport":"","examples":["Variants","WithAlertAction","TitleOnly"],"doc":"./ui__alert.md"},
   {"id":"ui/avatar","title":"UI · Avatar","description":"Avatar with fallback, image, sizes, group, badge.","layer":"ui","family":"Data display","tags":["ui","data","display","avatar","fallback","image","sizes","group"],"sourcePath":"src/components/ui/avatar","publicImport":"","examples":["Sizes","WithImageFallback","WithBadge","Group"],"doc":"./ui__avatar.md"},
   {"id":"ui/breadcrumb","title":"UI · Breadcrumb","description":"shadcn breadcrumb — list, items, separator (default & custom).","layer":"ui","family":"Navigation","tags":["ui","navigation","breadcrumb","shadcn","list","items","separator"],"sourcePath":"src/components/ui/breadcrumb","publicImport":"","examples":["Default","CustomSeparator"],"doc":"./ui__breadcrumb.md"},