themelia-react-ui 2.0.3 → 2.0.5

package/CHANGELOG.md

@@ -1,5 +1,190 @@
 # Changelog
 
+## 2.0.5 — 2026-10-31
+
+- Modal scrims render again under `SidebarProvider`/`AppSidebar`. The sidebar
+  drawer owner is a Dialog root around the app, so Base UI treated every dialog
+  inside as nested and skipped its backdrop. A modal now draws its backdrop
+  unless it opens from inside another modal's content.
+- Collection rows (menus, Command, Select, Combobox, cascader, global search) are
+  sized by their height role: block padding steps one tier below Item's, so a
+  single line is exactly 32/28/36px at default/compact/comfortable instead of
+  1.5px taller. DataTable menus, kanban and activities drop the legacy 24px
+  `density="table"` rows.
+- Skeletons use the translucent neutral chip fill, so they keep one contrast on
+  every surface, including a `--muted` sidebar where they used to disappear.
+- `StackedLayout`, `TopbarSidebarLayout` and `AppLayout` with no variant follow
+  the active theme; `headerTheme`/`light-header`/`dark-header` still scope the
+  header. Header controls (sidebar trigger, search, tools, notifications, a
+  one-line user trigger) share the 32px action height.
+- The dual navigation cluster docks its contextual panel from 768px beside a
+  primary rail and opens it as a drawer below that; `mobileSidebarMode="inline"`
+  keeps the previous docked cluster.
+- `GlobalSearch` input is a combobox with `aria-activedescendant`; results are
+  options reached with the arrow keys rather than Tab.
+- Filter editors focus their primary input when opened and share one editor
+  header; selection captions read "2 status selected" in running text.
+- Additive: `CardShell surface`, `FormSection titleSize`, CoordinatesInput
+  latitude/longitude accessible-label strings, MetricComparison `pointsUnit`,
+  UsageCard average-unavailable string, AI tool-call `elapsedLabel`, AI summary
+  `confidenceLabel`, ActivityRow `reserveDisclosure`/`reserveMenu`,
+  MediaLibraryToolbar `summary`/`disabled`, `useMediaLibrary().retry` and
+  `strings.retry`.
+- Alert places its action beside the copy only when the alert itself is wide
+  enough (container query), otherwise below it. PageHeader wraps its commands
+  below the copy before the copy column gets cramped.
+
+- `--height-action` and `--height-control` default to 2rem (32px) instead of
+  2.25rem. Their size steps are eighths of the root (¾, ⅞, 9⁄8), so the scale is
+  24/28/32/36px in whole pixels; it was 28/32/36/40px in ninths. Set the roots
+  back to 2.25rem to restore the previous heights (steps become 27/31.5/36/40.5px).
+- Corner roles: `rounded-radius` (`--radius`, 12px by default) is now the
+  default corner for buttons, inputs, select and facet triggers, badges,
+  collection and navigation rows and nested bodies. The new `rounded-surface`
+  (4/3 × `--radius`, 16px) is the larger corner of cards, popups, dialogs,
+  command shells and other outer surfaces. `rounded-inner` and its bounded
+  formula are removed. Migration: replace an app's `rounded-radius` on outer
+  shells with `rounded-surface`, and `rounded-inner` with `rounded-radius`.
+- `Alert` and the `Toaster` toast take Item's row geometry: the row insets
+  (`px-row-x`, `py-row-y`, 12px and 8px by default) and Item's 12px
+  media/actions gap, instead of the 24px card surface inset. A two-line notice
+  is about 60px tall instead of 94px. Overlay tone notices, which are Alerts,
+  follow the same row roles.
+- `PopoverTitle` and `PopoverDescription` no longer wrap plain text in the
+  popover's inherited line box, and `Cascader` keeps "Select current" beside
+  its title and path instead of inside the title row. A drilled level's title
+  and parent path now sit 4px apart instead of 11px.
+- Menu surfaces (popover menus and their header and footer bands, dropdown
+  menus, Select and Combobox lists, Command and its search row, global search,
+  mentions and the cascader) inset by md (8px) on both axes instead of xs
+  (4px) inline, so rows and the search field sit further from the edge, and
+  header and footer copy sit one small xs step (4px) inside that edge instead
+  of adding the full row inset (shared `popoverRecipes.menuCopyInset`).
+- Filters support nested options. `FilterOption.children` was declared but
+  ignored; `SELECT` and `MULTI_SELECT` editors now show nested options one level
+  at a time through the Cascader's panel (path search, Back, multi-select across
+  levels, `closeOnSelect`), and `SelectFacet` uses the `Cascader` field. A chosen
+  nested option reads as its path ("Europe / Greece / Athens") in chips and
+  facets. `FilterConfig.selectableOptions: 'any'` lets a branch be chosen, and
+  the filter strings add `previousLevel` and `selectCurrentLevel`. The panel is
+  a private part shared by `Cascader` and filters; `Cascader` behaviour is
+  unchanged.
+- `Cascader` moves between levels with motion: a drilled level or a new column
+  enters from the side it was reached from (shared `motionRecipes.level`,
+  `@starting-style`, reduced-motion aware). Opening and searching do not
+  animate the list.
+- `LayoutSidebarProvider` (and so `AppSidebar`) defaults to
+  `menuDensity="default"`: 28px primary rows and 24px nested rows on a 4px gap
+  (with the 2rem action height below), instead of comfortable 36px and 32px
+  rows. Pass `menuDensity="comfortable"` for 32px rows. Sidebar navigation
+  labels are medium weight throughout; the current entry is marked by its fill.
+  An unscoped base `SidebarMenuButton` falls back to the default density like
+  the rest of the menu, and a collapsed icon-rail row is the square of its own
+  height.
+- Remove the leftover `active:translate-y-0!` press overrides from Collapsible
+  and Tooltip triggers, dialog and sheet close buttons, popover buttons and the
+  sidebar trigger. Nothing translates on press any more, and the overrides made
+  triggers centred with a translate, such as the sidebar disclosure chevron,
+  jump down while pressed.
+- Add a fourth consumer skill, `themelia-design`, for the designer's part of a
+  view: a data brief read from real records, a view spec with ranked
+  information, wireframes and encodings, and a scored critique rubric with a
+  browser census for rendered screens. A `themelia-ui-designer` agent
+  definition applies it to whole views (design mode builds, renders and fixes;
+  review mode critiques read-only). `setup-skills.mjs --agents <directory>`
+  copies the agent without overwriting an existing file, and `--check`
+  compares it. The project-instructions block lists the new skill.
+- `ResourceCell` draws its media circle only when `imageUrl`, `icon` or
+  `fallback` is passed, and no longer falls back to a decorative mail glyph, so
+  order and invoice identifiers read as plain text. To keep a monogram for a
+  person or organization, pass `fallback={<Initials value={name} />}` (on every
+  row of a column where only some rows have a photo). An explicit `fallback`
+  still wins over `icon`, and `icon` now wins over title initials.
+- `InvoiceLineItems` states quantity and unit price once per narrow row instead
+  of repeating column labels, aligns header and rows on one subgrid with
+  content-sized numeric tracks, top-aligns custom cells, scrolls custom columns
+  horizontally (or drops columns marked `wideOnly` below its `@lg` width), and
+  adds `surface="flat"` for use inside a Card. Header and
+  rows now sit in `.invoice-line-items--body`, which carries the grid template
+  that each row used to repeat. The family
+  index now exports `InvoiceColumn`, `InvoiceLineItemsFooterRow`,
+  `InvoiceLineItemsStrings` and `defaultInvoiceLineItemsStrings`.
+- Commerce owners that hard-coded their frame accept `surface`/`padding`:
+  `FulfillmentGroup` (framed by default) and `InvoiceHeader`,
+  `DiscountStackPreview`, `TaxBreakdownCard`, `RefundStatusCard`,
+  `CartSummaryCard`, `ShipmentTracking` and `InventorySectionCard` (unframed by
+  default). Defaults are unchanged.
+- Add `maxVisibleSecondaryActions` to page, record, settings, workspace and
+  resource headers (default 2), `visibleFields` and `children` to
+  `ProductVariantEditor`, and `showGroupBy` to `ProductVariantsManager`
+  (default true).
+- Consumer gaps from the round-2 rebuilds: `InvoiceStatus` adds `draft` and
+  `disputed`; `InvoiceHeader.status` is optional and parties take `details`;
+  `OrderCustomer` adds `shippingMethod` and `showShippingAddress`;
+  `FulfillmentGroup` adds `count`; `MetricComparison` honours `current.trend`;
+  `ChartTooltipContent` adds `valueFormatter`; `ProductVariantEditor` adds
+  `errors`, `formId` and `showHeader`; `ResourceCell` adds `mediaShape` and a
+  full-title hover; `MediaResourceGallery` grid shows whole images and omits a
+  missing file size; an explicit DataTable column `size` sets its width without
+  resizing; `base/toaster` re-exports `toast`; `blocks/commerce` exports its
+  status tone maps and invoice strings. `ProductOptionsMatrix` focuses a value
+  added in its option editor so it can be typed at once.
+- Discovery resolves near-miss import paths with `importResolution`, the mapper
+  knows 139 roles across commerce, products, media, charts and analytics and
+  suggests nearby roles for unmatched phrases, and the inspector reads several
+  props at once and points hooks to their declaration. A new order and invoice
+  composition reference ships with executable recipes.
+
+## 2.0.4 — 2026-10-28
+
+Shared composition roles, stronger consumer guidance and executable component
+mapping. Existing public imports remain available; no structural token root or
+runtime dependency is added.
+
+- Restore shadcn neutral resting input borders in light and dark themes. Keep
+  the existing border/input/ring roles, focus and invalid indicators, sizing and
+  radius defaults; remove the blanket resting-border contrast override and its
+  enforcement. No CSS variable or public API is added.
+- Complete the implementation-guide corrections at shared owners: Card defaults
+  to the calm `card` surface, with an unruled header and a ruled footer. Explicit
+  `framed`, divider and provider overrides remain available. Surface roles use
+  the existing 12/16/24/32px scale; Card's supported padding and regional-gap tiers
+  are 12/24/32px. Control heights and radius defaults stay unchanged.
+- Centralize command, related-content, subject and page rhythm across layouts,
+  blocks and features. Page body and TwoColumnLayout columns space direct
+  sections consistently; resource headers and toolbars span above their grid.
+  Shared route, subject and subsection typography uses the existing scale.
+- Add `MetadataList adaptTo="container"` for narrow parent regions, retaining
+  viewport adaptation as the default. Resource and product/giftcard metadata
+  opt in. FormSection forwards Card's `padding`; PageHeading adds `titleSize`.
+- Simplify the RHF edit recipe with `Page render={<form />}` and automatic IDs
+  on direct controls. Preserve compound-control focus refs and forward Slider's
+  visible label/supporting descriptions to its native range input.
+- Split shell and example-page ownership, preventing duplicated route headers
+  and gutters. Repair responsive command-menu separator visibility with additive
+  `ActionMenuAction.groupClassName`. Clarify Card's opt-in `contentGap` without
+  changing its raw-child layout contract.
+- Ship `themelia-components`, `themelia-tokenization` and
+  `themelia-composition`, backed by one complete shared bundle of references,
+  typed recipes and domain templates. Foundation/forms paths and the shared
+  consumer skill remain compatibility routers; existing global skills are
+  preserved.
+- Add Node-only component/token inspectors with qualified API contracts,
+  generic/overload and callback detail, explicit omissions and unknown defaults.
+  Discovery retains exact/strict matching and adds qualified partial suggestions
+  with matched and missing terms when natural-language searches have no full match.
+- Add the advisory composition mapper: 36 exact components expose 40 roles,
+  supported slots, surface decisions, peers and unresolved needs. Authored
+  recommendations are validated against public TypeScript contracts; copied
+  and installed tools share the same metadata.
+- Document contextual component/parent ownership, complete-bundle copying and
+  template discovery. Restore static reference spacing from existing roots
+  instead of reading unshipped Tailwind aliases.
+
+When upgrading, refresh the complete copied skill bundle from the matching
+installed package. Card's calmer defaults remain overridable through explicit
+surface/divider props or UIProvider defaults; no consumer prop is removed.
+
 ## 2.0.3 — 2026-10-24
 
 Patch release of the audited UI and official Base UI compatibility fixes.

package/README.md

@@ -2,7 +2,7 @@
 
 A publishable React UI package built on Base UI and Tailwind, with shadcn-compatible themes and Themelia's public APIs. Routing, persistence, permissions and translations remain consumer-owned.
 
-Package: **`themelia-react-ui`** · current version: **`2.0.3`** · MIT licensed.
+Package: **`themelia-react-ui`** · current version: **`2.0.5`** · MIT licensed.
 The GitHub repository is `themelia-react-ui`; npm imports use `themelia-react-ui`.
 
 Consuming apps start with [consumer setup](#consumer-setup) and the packaged
@@ -25,6 +25,14 @@ npm run check:all
 
 The Vite React playground has foundations, a complete searchable catalogue, and an interactive products workspace. The catalogue groups Foundations (including semantic primitives and composition structures), Base components, Layouts, Blocks, and domain Features. Layouts includes five composed AppLayout presets (light header, dark header, sidebar, inset canvas and stacked navigation), plus a responsive composition guide for viewport grids, parent-driven grids, wrapping actions and stable content order. Navigation uses actual package families, static domain headings above Features, padded disclosures and a single Skeletons family page. Expansion persists across page changes and mobile drawer closure; search shows the same group context. `/` opens the full catalogue with preview-only hash navigation (`/?page=catalog` also works); `/?page=products` exercises options, generation, validation, async save/retry and bulk actions. React Router is not a dependency.
 
+For the application shell at its actual viewport size, open
+`/?page=shells&layout=header`, `/?page=shells&layout=sidebar` or
+`/?page=shells&layout=inset`; append `&theme=dark`
+for the dark theme. This preview-only mode removes catalogue chrome from the
+composition. The [shell architecture verification report](docs/verification/2026-10-29-shell-architecture-catalogue.md)
+records source ownership, rendered measurements and executed interactions for
+the three catalogue structures.
+
 `build` emits ESM entrypoints, TypeScript declarations, compiled component CSS, editable Tailwind theme source and optional map styles. Playground files stay outside the tarball. `check:contract` enforces exact exports, retained source symbols, component layers, dependencies and token ownership. `check:preview` verifies ready routes, example files, exact current public symbols, published imports and public family coverage. `check:docs` verifies local props for source-origin-qualified public callable owners, including all static displayed PropsTables. `check:package` requires a fresh `npm run build`. It installs the tarball into an isolated consumer, checks strict declarations for every family and matches installed declaration exports to the source-backed skill index. Its installed basic fixture checks SSR/hydration and executes provider defaults, controlled Input/Select/Checkbox state, form submission/validation/reset, scoped overlay portals and async confirmation/retry. Native links retain a separate strict typecheck and Vite-build smoke. The optional fixture exercises controlled table sorting/selection/visibility and client module initialization for specialist peers. Initialization does not establish specialist workflow or server-rendering support. It uses the configured npm cache, or `THEMELIA_NPM_CACHE`; a fresh `npm ci` cache may lack fixture registry metadata. Use `THEMELIA_FIXTURE_INSTALL=online` explicitly for cold temporary consumers, or supply a prepared cache for the default offline install. See [release readiness](docs/releasing.md).
 
 `lint` runs development-only `@shadcn/lint` through Oxlint: semantic colors across components, shared recipes and preview TSX and fixed typography contracts in preview examples. `check:design-lint` proves rule recognition, package stylesheet discovery and permitted customization. Both run inside `check`; `.oxlintrc.json` owns the staged policy. See [typography and lint guidance](docs/typography-and-design-lint.md).
@@ -48,17 +56,17 @@ Chromium 111+, Safari 18.1+ or Firefox 151+ for this theme behavior. The nearest
 mode class governs nested components and their scoped portals; see the
 [theme guide](docs/consumer-skill/references/theming.md) for partial overrides.
 
-Version 2.0.3 uses official `@base-ui/react ^1.9.0` from npm. Themelia's
+Version 2.0.5 uses official `@base-ui/react ^1.9.0` from npm. Themelia's
 `ComboboxRoot.dismissLabel` and feature `strings.dismiss` name both screen-reader
 dismissal controls. Shared popup owners preserve focus restored to a child
 trigger during deferred parent recovery. These behaviors are library-owned;
 consumers install the unmodified official Base UI package.
 
 ```sh
-npm install ./themelia-react-ui-2.0.3.tgz '@base-ui/react@^1.9.0' lucide-react
+npm install ./themelia-react-ui-2.0.5.tgz '@base-ui/react@^1.9.0' lucide-react
 ```
 
-After the initial registry release, install into a React 19 application with:
+For a registry release, install into a React 19 application with:
 
 ```sh
 npm install themelia-react-ui '@base-ui/react@^1.9.0' lucide-react
@@ -92,7 +100,30 @@ export function Example() {
 
 The default primary is near-black, so status colors never compete with it. For the Themelia green brand, also import `themelia-react-ui/themes/green.css` after `style.css`. For your own brand, set `--primary` and `--primary-foreground` (light and `.dark`) at the root or a `ThemeScope`; `--primary-accent` follows `--primary`.
 
-Compiled `style.css` requires no source scanning and includes no global preflight. Your app supplies its reset. Load library CSS before app overrides. A Tailwind v4 application can additionally import `theme.css` after Tailwind to use the same mappings in its own classes; this editable file contains Tailwind directives and needs processing.
+Compiled `style.css` requires no source scanning and includes no global preflight.
+Components own their essential font and box model; the host may supply a reset
+for its own markup. Keep resets in a lower-priority CSS layer and load deliberate
+app overrides after library CSS. A Tailwind v4 application can additionally
+import `theme.css` after Tailwind to generate app-owned utilities from the same
+mappings; this editable file contains Tailwind directives and needs processing.
+
+The package ships four focused agent capabilities:
+[components](docs/consumer-skills/themelia-components/SKILL.md) for installed setup,
+search and typed component/form integration;
+[tokenization](docs/consumer-skills/themelia-tokenization/SKILL.md) for domain
+structures combining public parts with semantic JSX and token-backed Tailwind,
+plus shared themes, typography and geometry;
+[composition](docs/consumer-skills/themelia-composition/SKILL.md) for business
+hierarchy, responsive screens and visual repair; and
+[design](docs/consumer-skills/themelia-design/SKILL.md) for reading records into
+view specs and scoring rendered views against a critique rubric. A
+[designer agent](docs/consumer-skill/agents/themelia-ui-designer.md) applies the
+design skill to whole views. Their shared assets and
+the compatible original entrypoint remain in `docs/consumer-skill`. The previous
+foundation/forms paths remain package compatibility routes; fresh skill copying
+installs the four canonical capabilities. Follow the
+[installed setup and copying guide](docs/consumer-skill/references/installation.md)
+to preserve all references; npm installation does not modify global agent skills.
 
 React component chunks preserve `"use client"` boundaries for frameworks such as Next App Router. Pure utilities remain server-usable. Navigation uses native links, callbacks and render composition supplied by the consuming app.
 
@@ -145,7 +176,8 @@ defines application freedom and library-owned anatomy; the
 and verification gate. Shipped consumer examples receive the same design lint as
 library compositions. Those repository checks do not run automatically in apps.
 Popover display/menu anatomy and default/compact insets are separate from collection
-row density and control size. Flush delegates padding to owned regions. Command
+row density and control size. Rich display surfaces keep 24px default insets;
+compact menu/list shells use 4px around their already-padded rows. Flush delegates padding to owned regions. Command
 search composes the public Input; features inherit these base recipes rather than
 rebuilding menu chrome or passing local padding overrides.
 
@@ -164,8 +196,8 @@ The common geometry controls are:
   --control-x: 0.75rem;
   --row-x: 0.75rem;
   --row-y: 0.5rem;
-  --surface-x: 1.25rem;
-  --surface-y: 1.25rem;
+  --surface-x: 1.5rem;
+  --surface-y: 1.5rem;
 }
 ```
 
@@ -173,10 +205,11 @@ The remaining roots cover icons/avatars, shell dimensions, content widths and ad
 
 Each default has one owner. There is no legacy token pipeline, JavaScript style engine, underscore prefix, or button-specific palette. Shared action/control, row, surface and text recipes prevent components from acquiring unrelated spacing or color systems.
 
-The additive copy-gap contract replaces scattered title/description gaps with
-`--gap-normal` (4px) and `--gap-dense` (2px), scaled once by `--space-scale`.
-Headed surfaces accept `textGap`, and Stack/Grid accept the same semantic gap
-values. Existing spacing tiers and public roots remain available.
+The [shared semantic-role contract](docs/consumer-skill/references/design-contract.md#semantic-roles)
+assigns copy, command, related-content, independent-subject and page rhythm to
+existing spacing tiers. It also names route/subject/subsection typography while
+preserving explicit sizes, semantic tags and provider scaling. Surface regional
+gaps remain derived from their insets; generic Stack/Grid defaults stay stable.
 
 ## Deliberate migration changes
 
@@ -216,17 +249,19 @@ The default development URL opens the full component catalogue. The focused foun
 
 `Button` separates `tone` from `buttonStyle` (`solid`, `outline`, `ghost`); the catalogue shows their matrix, sizes and loading/disabled states. Icon-only controls may omit children when an accessible label or tooltip is supplied. Badges use compact typography and insets rather than inheriting action geometry.
 
-Use `titleSuffix` for card status, count and version badges. `headerStart` is full-width pre-title context, and `headerAction`/`actions` own controls. Card owns token-spaced title/suffix wrapping for all surface modes. Give a card one quick control in `headerAction`, a command list in `actions` (its More actions menu) and the commit action in `footerSlot`; a framed card rules the footer off by default. Reserve body actions for a specific content step. Card owns aligned card insets, frames and expand/collapse behavior; Use `Card surface="flat" padding="none"` for card-free content hierarchy. ChartCard exposes `titleSuffix` too. Use `headerPlacement="frame"` for a header above an inset body. SmartCard and ContentBlock remain deprecated migration adapters; new code uses Card.
+Use `titleSuffix` for card status, count and version badges. `headerStart` is full-width pre-title context, and `headerAction`/`actions` own controls. Card owns token-spaced title/suffix wrapping for all surface modes. Give a card one quick control in `headerAction`, a command list in `actions` (its More actions menu) and the commit action in `footerSlot`; a framed card keeps its footer rule by default. Reserve body actions for a specific content step. Card owns aligned card insets, frames and expand/collapse behavior; Use `Card surface="flat" padding="none"` for card-free content hierarchy. ChartCard exposes `titleSuffix` too. Use `headerPlacement="frame"` for a header above an inset body. SmartCard and ContentBlock remain deprecated migration adapters; new code uses Card.
 
 Application drawers use `ActionDrawer` and `useOverlayVisibility` from `themelia-react-ui/features/overlays`. Sheet is the structural foundation and remains available for lower-layer infrastructure and compatibility.
 
 Header commands are role-based: one `primaryAction` and ordered
-`secondaryActions` render as `[secondary…] [primary] [⋯]`, with overflow,
-destructive commands and narrow widths moved into the More actions menu that
-ends the row. Page, PageHeader, PageHeading, the resource shells,
+`secondaryActions` render as `[secondary…] [primary] [⋯]`, with overflow
+and destructive commands moved into the More actions menu that ends the row.
+Below 40rem of actual header width, one More actions trigger contains all commands,
+including primary. Page, PageHeader, PageHeading, the resource shells,
 WorkspaceRecordHeader and SettingsShell share that row; keep `actions` for
-non-command controls. `header.tabs` puts a record's section tabs, with counts,
-under its header.
+non-command controls. Use `header.tabs` for separately selected or routed record
+sections, with counts when useful. Continuous detail documents keep their
+sections in the body.
 
 Every overflow menu shares one `ActionMenu` trigger: the `⋯` glyph named "More
 actions", a quiet ghost square in rows and cards (`context="inline"`, the
@@ -236,22 +271,107 @@ scale. The menu comes after any primary command in its row, and destructive
 entries stay last.
 Page owns inline and block padding, defaulting to the large surface role;
 PageViewport owns scrolling and supplies no inset. Use `Page narrow` for a
-centered single resource; explicit `maxWidth` wins. Page headers use dense copy
-gaps. Ordinary framed cards retain default `md` padding and rule header, body and
-footer apart by default; flat, card-free structure draws no rule unless asked. Set
-`card.defaultHeaderDivider` and `card.defaultFooterDivider` to `false` for an app
-that separates card regions by spacing alone.
+centered single resource. An `aside` selects the `xl` (80rem) measure unless
+`narrow` or an explicit `maxWidth` wins. Page owns `toolbar`, body lifecycle
+states (`loading`, `error`, `empty`, `onRetry`) and the route header.
+Its four header content slots are `beforeTitle`, `titleSuffix`, `afterDescription`
+and `actions`: pass React content or a callback receiving `{ renderLink, defaultContent }`.
+Compose Badge or MetadataList in those slots; the header adds no avatar or automatic
+metadata shape. `slots.actions` can wrap or return its default responsive command
+row through `defaultContent`; replacing it makes command behavior caller-owned.
+Legacy `slots.back`, `titleBadges`, `titleIcon` and direct `actions` remain supported.
+ResourceHeader, ResourceIndexShell, ResourceShowShell and TabbedResourceShell
+are deprecated; replace them with Page rather than nesting route owners. Their
+existing embedded geometry remains supported. Page headers use dense copy
+gaps. Ordinary cards default to `surface="card"` and `md` padding (24px), with
+an unruled header and a ruled footer. Explicit divider props override provider
+defaults. Use `surface="framed"` for grouped emphasis and `surface="flat"`
+inside an existing boundary. Card padding supports `none`, `sm` (12px), `md`
+(24px) and `lg` (32px); its default regional gap follows the same surface tier
+(`none` retains the 24px gap). The general surface scale also includes 16px. All
+are scaled once by `--space-scale`; control heights and corners remain separate.
+
+AppLayout keeps its five variant choices. The shared header-height root now
+defaults to `4rem`. Header-first
+`light-header`/`dark-header` layouts can opt into `contentSurface="inset"`: a
+quiet secondary canvas around the card-colored main surface. Sidebar-first
+`sidebar`/`inset` presets keep their existing flush/inset behavior. Shells own
+one PageViewport; Page supplies the page padding, and header partials occupy the
+shell's single header owner.
+
+The catalogue leads with three structures: a global Header shell, the shared
+App sidebar shell and a shadcn-style Inset shell. Single/dual navigation,
+attached/floating framing and collapse behavior configure these structures.
+They reuse the five presets. Full-size previews use
+`?page=shells&layout=header`, `sidebar` or `inset`, optionally with `&theme=dark`.
+The focused `grouped`, `dual`, `dual-inset`, `floating` and `stacked` views remain
+available for comparison.
+
+The featured layouts use grouped left navigation or a static left area rail
+beside a full navigation panel. Collapse is a caller choice on
+`AppSidebar`/`LayoutSidebar`, independent of the shell or sidebar skin:
+`collapsible="icon"` minimizes the full panel to icons, `"offcanvas"` hides it,
+and `"none"` keeps it expanded. Current examples default to `icon` and expose
+a preview selector for these modes. In a dual layout the primary area rail
+remains static: icon mode leaves a second compact column, while offcanvas
+leaves only the original rail. One explicit trigger controls the contextual
+panel; selecting an area opens it. Keep the primary rail's `collapsible="none"`
+policy independent of the adjacent panel's policy.
+At narrow widths the inline cluster pans a minimum page canvas while its area
+rail stays pinned; resizing does not silently minimize navigation.
+Both header-first and sidebar-first shells expose `mobileSidebarMode`; choose
+`inline` for this persistent cluster, or retain the default drawer policy.
+Sidebar shells accept
+`slots.sidebar` (primary) and `slots.secondarySidebar` (contextual), with named
+state inherited under one LayoutSidebarProvider. `openPanels` controls expansion and
+`mobilePanel` selects one shared undocked drawer while preserving desktop state.
+`navigationPanel` selects the untargeted trigger/shortcut destination. Existing
+primary `open`/`onOpenChange` remain supported; controlled `openPanels` takes
+precedence. Independent width props and `sidebarPresentation="rail"` use existing
+shell geometry, with no new public theme roots. SidebarNavigationRail supplies
+area navigation on its own background surface with one divider. Its dedicated
+width is 52px at the default roots (a 36px action plus 8px on each side); the
+existing full-sidebar icon-collapse width remains 60px. These are derived
+recipes, not new public settings. SidebarRail remains the collapse affordance.
+
 AppSidebar offers pinned `slots.headerStart`/`headerEnd` around its workspace
-region, compact navigation and a separated footer. The
+region, grouped navigation and a separated footer. The four `header`,
+`beforeNavigation`, `afterNavigation` and `footer` slots accept content or a
+callback with named state, renderLink and defaultContent. A header node preserves
+its legacy full replacement behavior; callback header content and either footer
+form retain library-owned insets. Before/after navigation content scrolls.
+Ordered `{ id, label?, items }` groups supplement the existing Record form, and
+`renderItemContent` customizes label content inside the accessible row. Use
+`currentUrl` for most-specific destination matching; render contexts distinguish
+the current item from its `ancestor`. In icon mode, searchable sidebars retain
+their search band as an icon that expands and focuses the field. Compact rows
+keep a small gap; default and comfortable density share a roomier row gap,
+with separate caption and group spacing. SidebarNavigationRail also exposes
+`header`, `beforeNavigation`, `afterNavigation` and `footer` slots: header/footer
+stay pinned and before/after content scrolls with navigation. Use
+`surface="transparent"` for navigation that shares a docked shell canvas;
+drawers remain opaque. `adaptTo="container"` keeps an embedded drawer and its
+backdrop inside the provider for compositions that use drawers. Omit a contextual
+group label when its header already supplies that same label. KPI peers use MetricGrid. The
 [complete shell recipe](docs/consumer-skill/examples/app-layout.tsx) demonstrates
-public workspace/account controls and application-owned callbacks.
+single- and multiple-region composition with public workspace/account controls
+and hosts route children directly. Its `contextualCollapsible` option defaults
+to `icon`; a supplied `secondarySidebar` can choose its own collapse mode. Its separate
+`WorkspaceExamplePage` owns the illustrative title, Create callback and narrow
+measure; a real route such as `AccountDetailPage` replaces that example.
 
 Choose one ordinary card surface through `card.defaultSurface`; explicit per-card
 surfaces win. Leave Card's `icon` slot for a glyph that carries state or a
 brand; titles name the subject. `headerPlacement` chooses inside/frame
 composition independently. Independent framed peers use `gap="2xl"`, matching
 Page and TwoColumnLayout's rhythm, since outer rings consume a smaller DOM gap.
-MetadataList (`themelia-react-ui/base/metadata-list`) keeps semibold labels and normal primary values in both densities.
+Card body children use the related (`xl`, 16px) gap by default; explicit
+`contentGap` remains authoritative. SettingsShell spaces direct sections by the
+subjects (`2xl`, 24px) role. MetadataList (`themelia-react-ui/base/metadata-list`)
+keeps semibold labels and normal primary values in both densities. It now adapts
+to its own container by default, with 22/28/38/52/64rem thresholds; pass
+`adaptTo="viewport"` to retain viewport breakpoints. DataTable owns its surface
+and topbar insets; place compact FilterLayout in `topbarContent`, or use DataView.
 Dashboard KPIs use Metric/MetricGrid/MetricBar; quotas use the focused UsageCard
 owner. See [analytics selection](docs/consumer-skill/references/analytics.md) and
 the [resource page recipe](docs/consumer-skill/examples/detail.tsx).
@@ -268,7 +388,7 @@ and ordinary Card subjects without app chrome. The packaged
 offers and real navigation links using the same theme and inset owners.
 
 
-Popover content uses `type="display"` for substantive content and `type="menu"` for collections. Mixed searchable menus use flush shells and compact region insets. `--radius` defaults to 12px. Cards and popup/command shells use `rounded-radius`; controls, collection/navigation rows and nested bodies use the shared, height-bounded `rounded-inner` role (normally 9px). Both derive from the same public root. Consumers inherit these recipes; see the [theme contract](docs/consumer-skill/references/theming.md) for scaling and custom roots. No separate surface/control radius setting is introduced.
+Popover content uses `type="display"` for substantive content and `type="menu"` for collections. Mixed searchable menus use flush shells and compact region insets. `--radius` defaults to 12px. Cards and popup/command shells use `rounded-surface`; controls, collection/navigation rows and nested bodies use the shared, height-bounded `rounded-radius` role (normally 9px). Both derive from the same public root. Consumers inherit these recipes; see the [theme contract](docs/consumer-skill/references/theming.md) for scaling and custom roots. No separate surface/control radius setting is introduced.
 
 
 ## Agent skill and consumer references
@@ -281,15 +401,17 @@ After installing the package, find a family using its real portable script:
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs form validation --limit 5
 ```
 
-Resolve the installed package and compare copied guidance using the [installed setup reference](docs/consumer-skill/references/installation.md). Copy its `docs/consumer-skill/` folder into your agent's skills directory as `themelia-react-ui-consumer/` to install the skill manually. For Codex, the default destination is `~/.codex/skills/themelia-react-ui-consumer/`. Preserve every subfolder; invoke `$themelia-react-ui-consumer` or let the agent select it. Refresh the copied skill when upgrading. Package installation, skill copying and registry publication are separate actions; none happens globally or automatically.
+Resolve the installed package and compare copied guidance using the [installed setup reference](docs/consumer-skill/references/installation.md). When skill installation is requested, use the bundled `setup-skills.mjs --copy --destination <agent skills directory>` helper. It copies the three focused skills and the compatibility/shared directory as a complete bundle, rebases links and includes templates. For Codex the usual destination is `~/.codex/skills`; preserve existing/customized skills and refresh the entire bundle together. Package installation, skill copying and registry publication are separate actions; none happens globally or automatically.
 
 Repository work uses the scoped [maintainer](docs/maintainer-skills/themelia-cn-maintainer/SKILL.md), [tokens](docs/maintainer-skills/themelia-cn-tokens/SKILL.md) and [quality](docs/maintainer-skills/themelia-cn-quality/SKILL.md) skills routed by [AGENTS.md](AGENTS.md). These repo-owned guides are excluded from the consumer package and do not replace separately installed skills.
 
-There is one packaged consumer skill with nine focused prose references, two
-generated indexes, fourteen typed recipe files and five helper scripts. Repository
-maintainer skills remain separate. The consumer entrypoint starts from task,
-context, information priority and command ownership and routes typography,
-layouts, theming, state/integration and verification detail to the relevant owner.
+The packaged consumer bundle contains `themelia-components`,
+`themelia-tokenization` and `themelia-composition`, plus one concise
+compatibility/shared entrypoint, API/component-contract/token metadata, typed
+recipes, helper scripts and references. The recipe manifest and copy helper own
+the current asset inventory; avoid copying an isolated skill file. Repository
+maintainer skills remain separate. The focused entrypoints route setup,
+composition and typed form work to their shared owners.
 Its [scoped directory recipe](docs/consumer-skill/examples/scoped-directory.tsx)
 shows one route heading, fixed parent context, integrated queries and record
 navigation. [Review and checks](docs/consumer-skill/references/review.md) describes
@@ -300,12 +422,22 @@ deterministic guidance infrastructure, not aesthetic judgment or new-task agent
 performance. Keep app-specific policy separate from the versioned package skill.
 
 Finder results include relevant symbols and focused next reads for declarations,
-references and exported recipes. This reduces the need to infer a component's
-purpose from its name or read every document before starting a screen.
+references and exported recipes. Zero-match natural-language searches can return
+qualified related suggestions with matched/missing terms. The Node-only
+`inspect-component.mjs` and `inspect-tokens.mjs` helpers retrieve bounded exact API
+contracts and distinguish public token roots from derived utilities. This reduces
+guessing without replacing the installed declarations for omitted or named types.
+
+The bundled [composition mapper](docs/consumer-skill/references/composition-mapping.md)
+uses per-symbol catalogue roles and supported regions to propose an advisory tree:
+`map-composition.mjs --pattern record-detail --main invoice-lines --aside facts`.
+It reports exact owners, surface decisions, peers and unresolved needs. Query
+`--roles` for the initial 36-component/40-role coverage; app implementation and
+visual review remain separate.
 
 Maintainers run `npm run docs:sync-skill` after changes to exports, types, selection guidance, peers or tokens. `npm run check:skill` requires a fresh library build and rejects stale source-backed references, built declaration exports and broken reference links. `prepack` checks source-backed references without rebuilding; `prepublishOnly` builds fresh assets and verifies built guidance. `check:package` verifies the complete shipped skill, strictly compiles the basic recipes without optional peers and every recipe with its required peers, and executes installed shell/resource-page and workflow checks.
 
-Build portable consumer documentation with `npm run build` followed by `npm run build:docs`. The generated [static entry](dist-docs/index.html) links to `dist-docs/2.0.3/` for the current version. Each version preserves the complete skill and all declaration files, supports search with the same finder, and uses relative links under any hosting subdirectory. Serve the entire artifact over HTTP; it needs no external CDN. Run `npm run check:static-docs` to check generated asset paths. The future hosting destination remains pending.
+Build portable consumer documentation with `npm run build` followed by `npm run build:docs`. The generated [static entry](dist-docs/index.html) links to `dist-docs/2.0.5/` for the current version. Each version preserves the complete skill and all declaration files, supports search with the same finder, and uses relative links under any hosting subdirectory. Serve the entire artifact over HTTP; it needs no external CDN. Run `npm run check:static-docs` to check generated asset paths. The future hosting destination remains pending.
 
 `npm run check:agent` runs focused agent-consumption fixtures and built skill alignment. `npm run check:release` performs the real serial local build/package/browser/agent/static-documentation gate; it does not publish or deploy. `npm run check:quick` runs the everyday core (contract, lint, design lint, typecheck, unit tests, build). See the [release guide](docs/releasing.md) and [draft changelog](CHANGELOG.md). There is no hosted CI; every check runs locally, when you choose. These commands verify locally; publication and deployment remain separate actions.
 

package/dist/{accordion-Cjb6sx0G.js → accordion-B9MHG0cT.js}

@@ -1,13 +1,13 @@
 "use client";
 import { useStrings as e } from "./lib/strings.js";
-import { t } from "./utils-BRhFDwuU.js";
-import { c as n } from "./typography-UTnveOEy.js";
+import { t } from "./utils-B6kKb8jB.js";
+import { c as n } from "./typography-BQnine1k.js";
 import { t as r } from "./focus-recipes-B653VaLq.js";
-import { t as i } from "./motion-recipes-ChBg4HBq.js";
-import { t as a } from "./structure-BmisBK-3.js";
+import { t as i } from "./motion-recipes-DitYv6P2.js";
+import { t as a } from "./structure-DuxKl954.js";
 import { t as o } from "./interaction-recipes-XR9ZpVYL.js";
 import { t as s } from "./disclosure-panel-B0HFNZ9x.js";
-import { t as c } from "./icon-badge-DYKIwvOV.js";
+import { t as c } from "./icon-badge-DZF-YjQp.js";
 import * as l from "react";
 import { forwardRef as u } from "react";
 import { jsx as d, jsxs as f } from "react/jsx-runtime";
@@ -61,7 +61,7 @@ function v({ className: e, children: n, render: r, ...a }) {
 var y = l.forwardRef(function({ className: e, ...n }, r) {
 	return /* @__PURE__ */ d(h, {
 		ref: r,
-		className: t("accordion--component rounded-radius border-border bg-card text-card-foreground", e),
+		className: t("accordion--component rounded-surface border-border bg-card text-card-foreground", e),
 		...n
 	});
 });
@@ -111,12 +111,12 @@ S.displayName = "AccordionContent";
 //#region src/components/base/accordion/accordion-variants.ts
 var C = {
 	card: "gap-space-md border-0 rounded-none bg-transparent text-inherit overflow-visible",
-	bordered: "rounded-radius border border-border bg-card text-card-foreground overflow-hidden",
-	flat: "border-0 rounded-none bg-transparent text-inherit overflow-visible"
+	bordered: "rounded-surface border border-border bg-card text-card-foreground overflow-hidden",
+	flat: "-mx-row-x w-auto border-0 rounded-none bg-transparent text-inherit overflow-visible"
 }, w = {
-	card: "border border-border bg-card text-card-foreground rounded-radius overflow-hidden",
+	card: "border border-border bg-card text-card-foreground rounded-surface overflow-hidden",
 	bordered: "bg-transparent not-last:border-b border-border",
-	flat: "border-0 not-last:border-b-0 bg-transparent rounded-radius overflow-hidden"
+	flat: "border-0 not-last:border-b-0 bg-transparent rounded-surface overflow-hidden"
 }, T = "items-center gap-space-lg px-row-x py-row-y text-start hover:no-underline", E = {
 	withMedallion: "ps-[calc(var(--row-x)*var(--space-scale)+var(--avatar)+0.75rem*var(--space-scale))] pe-row-x pt-0",
 	withInline: "ps-[calc(var(--row-x)*var(--space-scale)+var(--icon)*1.25+0.75rem*var(--space-scale))] pe-row-x pt-0",
@@ -205,4 +205,4 @@ function A({ iconStyle: e, icon: n, reserveSpace: r }) {
 //#endregion
 export { C as a, S as c, w as i, b as l, D as n, T as o, E as r, y as s, O as t, x as u };
 
-//# sourceMappingURL=accordion-Cjb6sx0G.js.map
+//# sourceMappingURL=accordion-B9MHG0cT.js.map