themelia-react-ui 2.0.3 → 2.0.5

package/docs/consumer-skill/references/composition-mapping.md

@@ -0,0 +1,106 @@
+# Executable composition mapping
+
+Use this when a screen needs several cooperating owners or when a component's
+surface and placement are unclear. The mapper resolves explicit responsibilities
+into exact public components and supported regions. The application still decides
+the user's priorities, data, commands and meaningful grouping.
+
+First resolve the installed package and verify copied guidance using
+[installed setup](installation.md). These commands assume its conventional
+`node_modules` location:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --roles
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --role facts
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --pattern record-detail --main invoice-lines --aside facts
+```
+
+For a complete copied bundle, use the shared skill's
+`scripts/map-composition.mjs` instead. It resolves `public-api.json` and
+`component-contracts.json` beside that script's shared references, independently
+of the current directory. Node is sufficient; the mapper does not load React,
+TypeScript, optional component peers or the consumer's application code.
+
+## Describe responsibilities, then inspect the plan
+
+1. Turn the business brief into independent subjects: for example invoice lines
+   in the main region and record facts in the supporting region. A responsibility
+   is a role tag reported by `--roles`; a complete business brief is not a role.
+2. Use `--role` to inspect a role's mapped owners. Role names accept spaces or
+   kebab-case. A phrase that matches no role stays `unresolved` and may list
+   `suggestedRoles` that share its words; retry with one of them only when it
+   names the same job. A qualified `themelia-react-ui/<family>#<Symbol>` selector chooses
+   an exact mapped contract when a role has several candidates.
+3. Select a pattern and repeat `--main` or `--aside` for each subject. Supported
+   patterns are `record-detail`, `collection`, `edit`, `analytics` and `embedded`.
+   They identify structural context; they do not install form state, fetch data
+   or choose application-specific variants. Edit plans explicitly retain the
+   application's native form and submission requirements.
+   Use `--limit 1..10` to bound candidate details; it does not discard requested
+   subjects or hide unresolved coverage.
+4. Read `tree`, `coverage`, `unresolved`, `warnings`, `requiredPeers`,
+   `applicationOwns` and the focused `nextReads` before implementing. Inspect each
+   chosen unfamiliar component with the [API inspector](discovery.md#inspect-a-selected-component).
+
+`requiredPeers` lists the selected families' additional optional package peers;
+`baselinePeers` lists the package's nonoptional peers. Both still require the
+installed setup and matching versions. An empty additional list does not remove
+React or Base UI requirements.
+
+The record-detail example resolves a route owner and, because support is
+requested, Page's mapped aside slot. Without support, edit/detail plans recommend narrow when its contract supports that prop. Its `tree.slots` uses actual insertion props
+such as `children` and Page's direct `aside`. Older bundles without Page aside anatomy retain their explicit main/support layout. Parent-surface content can receive a
+subject Card at that boundary. Already framed owners keep their own surface;
+variant-dependent owners require inspection before choosing framing.
+
+Collection plans can place an explicit toolbar need in the table seam:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --pattern collection --main comparison-table --main query-toolbar
+```
+
+The mapped FilterLayout goes into DataTable's topbarContent with compact/clear
+props, and the mapped FilterProvider wraps that table. Supply its definitions,
+activeFilters and onFilterChange using the app's query transport. Toolbar order
+in the request does not matter. Missing/ambiguous table seams or context mappings
+remain unresolved; no detached filter strip or guessed provider is emitted.
+
+For an existing Card boundary:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --pattern embedded --parent Card --main facts
+```
+
+That plan uses the selected host's `children` region without adding another Page
+or Card. Qualify an ambiguous parent with `--import <exact public import>`.
+An embedded request without a parent leaves the host decision explicit; inspect
+its unresolved ownership before creating a new boundary.
+Only an explicitly declared route-child slot permits a Page inside a shell;
+AuthShell and bounded workspaces are ordinary content hosts. Variant-dependent
+hosts retain inspection warnings before another framed subject is added.
+
+## Read the result's scope
+
+The output is advisory JSON. `mapped` means the requested roles resolved under
+the mapper's supported contracts. It does not mean an application is implemented,
+accessible, visually accepted or ready for delivery. `partial` and `unresolved`
+retain requests the mapper could not place or uniquely identify; choose a more
+specific role or qualified mapped owner. Metadata coverage is deliberately
+explicit: an unmapped component can still be a valid public component.
+
+Mappings belong to exact import/symbol pairs in the existing authored catalogue,
+then flow into its generated public index. They describe role tags, owner kind,
+region/cell/overlay placement, surface ownership, insertion props and any authored
+literal recommendations. Generation checks them against the actual public API.
+They do not introduce another theme, token system or component registry.
+
+Table-cell identities stay in column renderers, and overlays stay at their
+composing app/feature boundary. Similar collection owners remain alternatives;
+a request that cannot distinguish them stays unresolved. App data, callbacks,
+permissions, forms and asynchronous lifecycle still follow the selected owner's
+contract and matching recipe.
+
+Use [composition ownership](composition.md), [screen archetypes](screen-archetypes.md)
+and [form workflows](rhf-workflows.md) for the selected task. After implementing,
+run the existing source checker and app checks, inspect narrow/wide light/dark
+appearance, and execute the relevant interactions from [review](review.md).

package/docs/consumer-skill/references/composition.md

@@ -1,6 +1,6 @@
 # Composition
 
-The [design contract](design-contract.md) separates application layout freedom
+The [design contract](design-contract.md#semantic-roles) defines shared spacing and typography roles and separates application layout freedom
 from library-owned anatomy. Use supported props and slots inside shared surfaces;
 keep placement, width, wrapping and overflow with the surrounding composition.
 
@@ -16,6 +16,12 @@ keep placement, width, wrapping and overflow with the surrounding composition.
 | Reusable subject presentation | Blocks |
 | Editing/selection/async lifecycle | Features with app callbacks |
 
+Base controls, layouts and blocks also own their local interaction and
+accessibility; features coordinate a complete business workflow. For choosing
+compound APIs and building token-backed app content, read
+[app-owned composites](custom-composition.md). It includes disclosure sections,
+layer boundaries and a custom comparison seam.
+
 ## Compose from the task
 
 Identify the user's next decision before selecting components. Establish fixed
@@ -29,11 +35,11 @@ a detail workspace or a form; they need different information hierarchies.
 | DataView | Its coordinated query, view and collection lifecycle fits | DataTable with app-owned query transport and native toolbar slots when coordination differs; base Table for presentation without TanStack behavior |
 | ResourceCell | Identity inside a table cell | Item for independent list entries; MetadataList for label/value facts about one subject |
 | Page / application shell | Route identity, navigation, content bounds and page commands | Card for an independent subject within that route; do not repeat the same heading merely to frame a table |
-| Card | One subject needs a frame and headed regions | `surface="flat" padding="none"` inside an existing boundary; nested DataTable uses its own `surface="flat"` |
+| Card | One subject needs a frame and headed regions | `surface="flat" padding="none"` inside an existing boundary; prefer DataTable directly in the layout, or Card padding="none" with a flat table |
 | Metric / MetricGrid / MetricBar | A KPI needs formatted value, comparison/trend or peer layout | UsageCard for used/limit quotas; InlineStat for one plain fact, MetadataList for several record facts |
 | FormField / InlineEdit | A field needs label/hint/error, or isolated save/cancel | Complete feature/overlay for a workflow; app form owns whole-record submission |
 
-For a DataTable composition, put queries in `topbarContent`, exports or collection
+For a DataTable composition, wrap it in FilterProvider and put `FilterLayout variant="compact" showClearFilters` in `topbarContent`, exports or collection
 tools in `topbarEnd`, selection commands in `bulkActions`, and record commands
 in `rowActions`. `bulkActions` render in the shared `BatchActionBar`, docked to
 the viewport while rows are selected (`selectionToolbarPlacement="inline"` keeps
@@ -57,18 +63,22 @@ or supported comparison controls. Avoid automatically appending every hidden
 column to identity metadata. There is no universal row-line limit: long names,
 accessibility needs and the task can justify richer rows. Explain the priority.
 Custom ResourceCell metadata is caller content; use shared supporting typography
-and CellStack where its smaller secondary-value contract fits.
+and CellStack where its smaller secondary-value contract fits. ResourceCell draws
+its media circle only when you pass `imageUrl`, `icon` or `fallback`: order and
+invoice identifiers stay plain text, and a person opts in with
+`fallback={<Initials value={name} />}`.
 
 Commands need explicit importance as well as scope. Describe page commands by
 role in Page's header: `primaryAction` is the route's one main command, and
 `secondaryActions` lists supporting commands in priority order. The header owns
 their treatment and order: outline secondary buttons, the solid primary button,
 then a More actions menu for overflow, destructive commands and narrow screens,
-which always ends the row. WorkspaceRecordHeader, ResourceHeader, the resource
+which always ends the desktop row. Below 40rem of actual header width, every
+command, including primary, moves into one More actions menu. WorkspaceRecordHeader, ResourceHeader, the resource
 shells and SettingsShell take the same props and render the same row. Choosing which
 command is primary, which are `destructive`, and which are `visible` remains an
 application decision; confirm destructive commands in their handler. Use
-`actions` only for non-command controls such as a period select. A back link,
+the compatible direct `actions` prop for non-command controls such as a period select. A back link,
 export and destructive command should not all inherit the same visual emphasis.
 
 ```tsx
@@ -82,7 +92,8 @@ export and destructive command should not all inherit the same visual emphasis.
 }}>{/* route content */}</Page>
 ```
 
-A record split into sections adds `header.tabs`. The tabs sit under the header's
+When a record has separately selected or routed sections, use `header.tabs`.
+A continuous detail document can keep its sections in the body. The tabs sit under the header's
 copy and commands, a `badge` shows a count, tabs that do not fit move into a More
 menu, and `onValueChange` switches the section or routes. Labels name the
 command; an icon on every command repeats it, so keep `+` on an add command and
@@ -91,7 +102,7 @@ leave the others plain.
 ```tsx
 <Page header={{
   title: member.name,
-  titleBadges: [{ label: 'Needs attention', tone: 'warning' }],
+  slots: { titleSuffix: <Badge tone="warning">Needs attention</Badge> },
   primaryAction: { label: 'Generate report', onClick: onReport },
   secondaryActions: [
     { label: 'Update profile', onClick: onEdit },
@@ -209,7 +220,7 @@ See the [website example](../examples/website.tsx) for both hero and section emp
 
 ## Card anatomy
 
-Card surface="card" is the ordinary bordered surface; surface="framed" retains its ring recipe; surface="flat" padding="none" composes within an existing boundary. headerPlacement="frame" places title/icon/actions above an inset body, retaining default corners and using rounded-inner on that body.
+Card surface="card" is the ordinary bordered surface; surface="framed" retains its ring recipe; surface="flat" padding="none" composes within an existing boundary. headerPlacement="frame" places title/icon/actions above an inset body, retaining the surface corner and using rounded-radius on that body.
 
 Choose one ordinary Card surface through UIProvider's `card.defaultSurface` and
 let sibling subjects inherit it. Explicit per-card surfaces win: mixing `card`
@@ -222,21 +233,39 @@ for richer content. Facts and rows follow the same rule: one glyph repeated on
 every MetadataList item or Item row is decoration, so leave `icon`/media empty.
 
 Card `gap` owns spacing between regions; `contentGap` owns direct body-child
-spacing; `textGap` owns title/supporting-copy rhythm. Region spacing defaults to
-`xl` (`md` for `padding="none"`). Use a semantic region gap for compact cards
-instead of resetting padding or adding local margins.
-
-Ordinary independent cards omit `padding` and retain `md` (the full surface
-inset, 20px at default roots). `sm` is half that inset (10px), for a deliberately
-compact subject; it is not the default for forms, settings, metrics or resource
-pages. Component size and
-density do not choose Card padding. `lg` uses 1.8 times the inset (36px), while
-`none` removes it. All sizes follow the surface roots and space-scale.
-Card dividers are on by default: a framed card rules its header and footer apart,
-while flat, card-free structure and a `headerPlacement="frame"` header draw no
-rule unless asked. UIProvider's `card.defaultHeaderDivider` and
-`card.defaultFooterDivider` (both `true`) turn the framed rules off app-wide;
-explicit per-card booleans win. Header/footer-only cards render one shared divider.
+spacing; `textGap` owns title/supporting-copy rhythm. Body children default to
+the shared related `xl` gap (16px at default roots).
+Use `contentGap="2xl"` for
+independent sections. Omit it around an existing Grid/Stack or a single feature
+that already owns its layout:
+
+```tsx
+<Card title="Billing" contentGap="xl">
+  <MetadataList columns={1} items={[
+    { label: 'Plan', value: 'Studio' },
+    { label: 'Billing cycle', value: 'Monthly' },
+  ]} />
+  <Text type="secondary" size="xs">Invoices go to billing@northstar.example.</Text>
+</Card>
+```
+
+This lets Card own body rhythm without an extra caller wrapper. For independent sections,
+change the Card to `contentGap="2xl"` and let each section own its heading/copy
+group. The default regional gap
+follows the surface inset tier: 12px with `padding="sm"`, 24px with omitted/`md`
+or `none`, and 32px with `lg`, before spacing scale. An explicit semantic `gap`
+overrides it without changing the insets. See [semantic roles](design-contract.md#semantic-roles).
+
+Ordinary independent cards omit `padding` and retain `md` (24px at default
+roots). Card supports `sm` (12px), `md` (24px), `lg` (32px) and `none` (no inset).
+The general surface scale also has a 16px tier; Card does not expose it as a padding prop.
+Component size and density do not choose Card padding. All tiers follow the
+surface roots and space-scale.
+Card defaults to `surface="card"`, with no header rule and a footer rule.
+Flat, card-free structure and a `headerPlacement="frame"` header draw no rule
+unless asked. UIProvider's `card.defaultHeaderDivider` (false) and
+`card.defaultFooterDivider` (true) configure these rules app-wide; explicit
+per-card booleans win. Header/footer-only cards render one shared divider.
 Inside the body, separate a card's sections with `contentGap` or a Stack gap
 clearly larger than the row gap (`2xl` between sections), not rules.
 Overlays rule their regions the same way: `ActionDialog`, `ActionDrawer` and `ConfirmDialog`
@@ -306,26 +335,27 @@ primitives rather than replacing labels and values with undifferentiated Text.
 
 ## Menus and controls
 
-PopoverContent type="display" owns substantive-content padding; type="menu" compact collection padding around already-padded rows. Popover and Command share inset="default" and inset="compact" paradigms. Mixed searchable shells use inset="flush"; public header/search/list/footer anatomy owns its insets automatically. CommandInput composes the public Input for control geometry and focus styling; its search region adds only outer spacing. Do not pass padding through className, contentClassName or inline styles. Compact header controls and footer actions align with row highlight edges; header text and footer captions align with row labels. Use PopoverHeader start for a leading control and PopoverFooter caption for supporting content alongside trailing action children. Dividers use the same semantic recipe. density selects vertical row rhythm without changing inline padding. ActionMenu owns action definitions, PopoverMenu searchable selection, DropdownMenu bespoke menu anatomy. Shared appearance preserves their accessible menu/listbox/dialog behavior.
+PopoverContent type="display" owns substantive-content padding; type="menu" compact collection padding around already-padded rows. Popover and Command share inset="default" and inset="compact" paradigms. Mixed searchable shells use inset="flush"; public header/search/list/footer anatomy owns its insets automatically. CommandInput composes the public Input for control geometry and focus styling; its search region adds only outer spacing. Do not pass padding through className, contentClassName or inline styles. Compact header controls and footer actions align with row highlight edges and the search field; header text and footer captions sit one small step inside that edge. Use PopoverHeader start for a leading control and PopoverFooter caption for supporting content alongside trailing action children. Dividers use the same semantic recipe. density selects vertical row rhythm without changing inline padding. ActionMenu owns action definitions, PopoverMenu searchable selection, DropdownMenu bespoke menu anatomy. Shared appearance preserves their accessible menu/listbox/dialog behavior.
 
 | Choice | Responsibility |
 | --- | --- |
 | PopoverContent type="display" / type="menu" | Display versus collection anatomy and typography |
-| inset="default" / "compact" | Full versus half surface-root inset |
+| inset="default" / "compact" | Rich surface inset versus small collection shell |
 | inset="flush" | Delegate insets to owned regions; not a density |
 | density="compact" / "default" / "comfortable" | Collection row block rhythm, independent from inline spacing |
 | size="sm" / "md" / "lg" | Supported control's scale; consult its declaration and provider precedence |
 
-Input, Button, Select and filter-facet triggers share bounded inner corners
-and corresponding heights; Card and popup shells use the global outer radius. Omitted sizes inherit the provider; explicit sizes win.
+Input, Button, Select, filter-facet triggers and badges share the default
+`rounded-radius` corner and corresponding heights; Card and popup shells use the
+larger `rounded-surface`. Omitted sizes inherit the provider; explicit sizes win.
 Keep action/control roots equal when those controls adjoin. Compact menu rows,
-surface insets and control sizes remain independent; density can tighten the
-inner-radius height bound without changing outer corners.
+surface insets and control sizes remain independent; density does not change
+the corner.
 Inset segmented children use the supported compound owner's same-height frame.
 
 PopoverContent defaults to display/default; Command defaults to compact. An explicit PopoverContent type controls anatomy; explicit inset controls padding and takes precedence over the type's inferred inset. Without type, compact implies menu, other insets imply display. Put type="menu" inset="flush" on PopoverContent for a headed searchable picker. Popover is the interaction root and receives no surface props. PopoverMenu already assembles that picker anatomy; use its declared selection/search props. ComboboxPopup is flush because ComboboxList owns its inset. Do not add another wrapper inset around a normal collection list.
 
-At shipped roots, compact shell padding is 8px; row inline padding is 12px; default row block padding is 8px and minimum height 36px. Compact/comfortable rows use 6/10px block padding and 32/40px minimum heights. Content can grow when it wraps. These are token-derived measurements, not app constants. Flush compact header/footer shell padding matches the list (8px inline). Header text bodies without a leading control and footer captions add the row inset once, aligning text at 20px. Actions keep the 8px shell edge. Nested public slots do not repeat these insets.
+At shipped roots, rich display padding is 24px and compact collection shell padding is 8px; row inline padding is 12px; default row block padding is 8px and minimum height 32px. Compact/comfortable rows use 6/10px block padding and 32/40px minimum heights. Content can grow when it wraps. These are token-derived measurements, not app constants. Flush compact header/footer shell padding matches the list (4px inline). Header text and footer captions add a small xs step (4px) to the md band inset (8px), rather than the full row inset. Actions keep the 4px shell edge. Nested public slots do not repeat these insets.
 
 Input frames and outline buttons share the input semantic token; collection dividers use border/60; focus uses ring separately and draws one indicator everywhere (a full-strength edge inside a soft halo). Equal responsibilities share recipes, while different semantic roles retain their own treatment. CommandInput keeps its existing onValueChange search contract and native refs; use the actual public Input through its default composition rather than restyling an unframed native field.
 
@@ -427,6 +457,40 @@ to the existing shell and retains its typed slots; topbar props and toolbar
 props are specific to their variants. The low-level TopbarSidebarLayout,
 SidebarInsetLayout and StackedLayout remain available for deliberate composition.
 
+Choose the structure before its options: a global Header above navigation, a
+full-height AppSidebar beside the content Header, or the shadcn-style inset page
+beside navigation. The catalogue leads with these three structures and reuses
+the exact AppSidebar example from the Sidebar page. Single/dual navigation,
+attached/floating frames and icon/offcanvas collapse configure a structure.
+Example child destinations are text-only; an explicit child icon is reserved
+for a case where it carries information.
+
+Header-first light/dark variants accept `contentSurface="inset"` for a quiet
+secondary canvas around the card-colored main surface; omission keeps plain.
+SidebarInsetLayout retains `surface="inset" | "flush"`, and the sidebar/inset
+presets retain their defaults. AppSidebar/LayoutSidebar `surface="transparent"`
+shares the docked canvas; drawer surfaces remain opaque. This uses the existing
+theme roles and structural roots.
+
+The shared global header-height root defaults to 4rem. Use the playground's
+full-viewport `?page=shells&layout=header|sidebar|inset` views to inspect
+the composition, optionally with `&theme=dark`.
+
+Sidebar shells accept `slots.sidebar` (primary) and `slots.secondarySidebar`
+(contextual navigation). Each missing region removes its track. `sidebarWidth`
+and `secondarySidebarWidth` size their own expanded region, with the
+shared shell width as fallback. `sidebarPresentation="rail"` selects dedicated
+primary navigation geometry independently of full-sidebar icon collapse. Use SidebarNavigationRail from
+layout/sidebar for area navigation with items, value/onValueChange and
+renderLink; it preserves accessible labels/tooltips and defaults to
+collapsible="none". Its default background surface and divider distinguish it
+from the contextual canvas. The 48px default derives from a 32px action plus
+two 8px insets; full-sidebar icon collapse remains 60px. These are private
+recipes, not extra consumer knobs. SidebarRail remains the collapse affordance.
+The rail also accepts header, beforeNavigation, afterNavigation and footer
+nodes or render callbacks with named state. Header/footer are pinned;
+before/after content scrolls with its navigation.
+
 The shell owns one PageViewport and framing. Give the root a constrained height
 (`h-svh min-h-0` for full-screen apps). Page owns width, page gutters and
 header/body rhythm, Card owns its insets, and Stack/Grid owns peer gaps. With
@@ -434,12 +498,49 @@ stacked/contained content, use Page gutter="none" to avoid repeating the shell's
 Container gutter. Metric card size changes copy/media scale, keeping the default
 surface inset in ready, loading and error states.
 
-Compose LayoutSidebarProvider around AppSidebar and SidebarTrigger. Use
-`adaptTo="container"` on the provider for embedded workspaces: it measures its
-own width and switches navigation to the same mobile drawer below 768px, even
-on a wide viewport. The default remains viewport-driven. Account/search/page
-actions remain application callbacks. Do not add another scroll viewport
-inside the page. Header menus retain the header theme through their portal host.
+Keep the dual area rail docked on the left beside the full navigation panel,
+and choose that panel's AppSidebar/LayoutSidebar `collapsible` independently
+of its skin or AppLayout variant. `icon` minimizes it to a second compact
+column, `offcanvas` hides it and leaves only the original rail, and `none`
+keeps it expanded. Current examples default to `icon` and expose a preview
+selector for the same modes; standalone navigation supports the same choice.
+The primary area rail keeps its own `collapsible="none"` policy. One explicit
+trigger controls the contextual panel; selecting an area opens it. At narrow widths the inline cluster pans a
+minimum page canvas while its area rail stays pinned. It preserves the chosen
+expansion state rather than silently minimizing. Do not repeat a contextual
+group heading already supplied by its pinned
+header. KPI peers use MetricGrid. Shared header/page/navigation recipes own the
+spacing; Page remains the one page-padding owner.
+
+Compose one LayoutSidebarProvider around the shell and its triggers. Shell slots
+establish named scopes, so AppSidebar, LayoutSidebar and useLayoutSidebar() infer
+their panel ID; ordinary compositions need no repeated IDs or nested provider.
+Manual compositions can pass a panel ID explicitly. `SidebarTrigger panelId`
+targets primary/secondary/aside; omission uses provider `navigationPanel`
+(primary by default). That also selects the Ctrl/Command+B shortcut target;
+keyboardShortcut changes the key or accepts false.
+
+Desktop expansion uses openPanels/defaultOpenPanels/onOpenPanelsChange. Closed
+icon panels leave a rail, offcanvas removes their track, and none remains visible.
+Controlled openPanels wins over legacy primary open; otherwise open controls
+primary and the provider owns other regions. defaultOpenPanels defines the
+initial uncontrolled set; without it, defaultOpen keeps its primary meaning.
+Primary changes notify onOpenChange and set changes notify onOpenPanelsChange.
+The app accepts controlled proposals by updating the matching props; additional
+persistence remains application-owned.
+
+mobilePanel/onMobilePanelChange select one active undocked drawer, preserving
+desktop preferences. Context presentation is docked/drawer; isMobile is its
+drawer alias, including when a contextual panel undocks on a desktop viewport.
+Other panel/drawer compositions retain default thresholds of 768/1024/1440px
+for primary/secondary/aside against available shell width. The featured dual
+cluster uses `mobileSidebarMode="inline"` to keep the rail and its adjacent
+collapsible panel docked. Use adaptTo="container" on embedded providers to contain
+their drawer and backdrop inside that provider. Essential
+undocked regions need reachable targeted triggers. Account/search/page actions
+remain application callbacks. Do not add another scroll viewport inside Page.
+Use Header partials in shell slots to retain one header/inset owner. Header menus
+retain the header theme through their portal host.
 
 Header forwards native attributes, handlers and refs. PageHeader supports
 textGap="normal" or "dense" without changing control or page insets. Header
@@ -448,11 +549,27 @@ TwoColumnLayout defaults to its existing viewport breakpoint; choose
 adaptTo="container" inside Container/PageViewport to adapt at 48rem of usable
 parent width while preserving main-before-aside DOM/focus order.
 
-See the installed [workspace recipe](../examples/app-layout.tsx).
+The installed [app-shell recipe](../examples/app-layout.tsx) exports a copyable
+`WorkspaceLayout` that hosts route children directly. Put `AccountDetailPage` or
+another route Page inside it. `WorkspaceExamplePage` separately demonstrates a
+Workspace title, Create callback and narrow measure; replace that example when
+composing a real route. `WorkspaceRegionsLayout` accepts primaryNavigation and
+sidebarPresentation="rail" for a static SidebarNavigationRail beside contextual
+navigation; omitted primaryNavigation builds the alternative grouped sidebar.
+It coordinates controlled named state under one provider. The app's area rail
+can use useLayoutSidebar('secondary') to open context when an area is selected.
+A defined
+secondarySidebar replacement wins over contextualNavigationGroups; null removes
+that region. Without a replacement, groups build the standard AppSidebar with
+`contextualCollapsible?: AppSidebarProps['collapsible']`, defaulting to `icon`.
+Pass `offcanvas` to hide it or `none` to retain expanded navigation; a supplied
+secondarySidebar owns its own policy. These recipe names are
+local to the copied file; the public
+`WorkspaceLayout` from `layout/workspace` is the record shell described below.
 
 PageViewport owns scrolling and adds no padding. Page defaults to `gutter="lg"`
-and `padding="lg"` (36px at shipped roots), so it owns inline/block space once.
-`narrow` selects centered `md` width; explicit `maxWidth` wins. Header copy
+and `padding="lg"` (32px at shipped roots), so it owns inline/block space once.
+`narrow` selects centered `md` width (48rem); otherwise an aside selects `xl` (80rem), and a single column uses `lg` (64rem). Explicit `maxWidth` wins over both. Header copy
 defaults to dense; `textGap="normal"` is an explicit alternative. Do not assume
 an app shell supplies gutters because it supplies a viewport. Set `gutter="none"`
 only when an actual parent Container/surface supplies the inline inset, such as
@@ -460,14 +577,33 @@ StackedLayout's contained mode. Block padding remains independent.
 That contained measure uses the same large gutter as Page; ordinary Container
 defaults remain unchanged.
 
+
+Page is the canonical route owner for new index/detail/edit screens. Its header
+keeps title, description, back navigation, commands and tabs. Add content through
+`header.slots.beforeTitle`, `titleSuffix`, `afterDescription` and `actions`.
+Each accepts a React node or a callback receiving `{ renderLink, defaultContent }`.
+Compose Badge for a title status and MetadataList for facts below the description;
+there is no automatic metadata item shape or avatar column. Title, description and afterDescription stay in one tight left copy column;
+actions occupy a separate right column aligned to the top. beforeTitle spans
+above the columns, and tabs sit below. An actions renderer
+can wrap or return `defaultContent` to retain the responsive command row; replacing
+it owns its own command semantics. Legacy `slots.back`, `titleBadges`, `titleIcon`
+and direct `actions` remain compatible. Direct toolbar, aside and lifecycle props compose at that
+same boundary; explicit slots override matching direct regions. beforeHeader
+precedes the header; afterHeader is the compatible toolbar fallback. Loading
+precedes error, then empty, replacing only the main body while the header,
+toolbar and aside remain mounted. Customize state strings or loading/error/empty
+slots and wire onRetry. ResourceHeader/ResourceIndexShell/ResourceShowShell/
+TabbedResourceShell retain legacy embedding behavior for migration.
+
 Select width from the task: a single focused resource/form can use `narrow`;
-a record with a supporting aside can retain the default `lg` measure and use
-TwoColumnLayout. A wide comparison/directory can deliberately use `maxWidth="full"`.
+a record with supporting context uses Page `aside` and infers `xl` (80rem).
+An explicit TwoColumnLayout inside Page should set `maxWidth="xl"`; it retains its own split contract. A wide comparison/directory can deliberately use `maxWidth="full"`.
 Setting full on every route defeats the resource measure. Do not remove Page's
 gutters to make its title touch the sidebar; align the header and body through
 the same Page. Density, container measure and page inset are separate choices.
 The [detail recipe](../examples/detail.tsx) includes `AccountDetailPage`: the
-default record measure, a status badge, route-level commands and section tabs in
+narrow record measure, a status badge, route-level commands and section tabs in
 the header, and MetadataList facts in one framed Card, with no duplicated subject
 header or gutter.
 
@@ -475,9 +611,23 @@ Compose HeaderUserMenu in topbar `slots.headerEnd` or a local toolbar, and
 SidebarNavigationUser in AppSidebar `slots.footer` when account access belongs
 in navigation. Use SidebarWorkspaceDropdown for workspace links, or add a
 custom control through `slots.headerEnd` alongside the logo. `headerStart` and
-`headerEnd` stay inside the padded, fixed header; `slots.header` replaces it all.
-`beforeNavigation` scrolls with the links. SidebarFooter owns its rule and inset.
-LayoutSidebarProvider defaults to compact row gaps; explicit density still wins.
+`headerEnd` stay inside the padded, fixed header. The four header,
+beforeNavigation, afterNavigation and footer slots accept nodes or callbacks
+receiving `{ panelId, collapsed, presentation, isMobile, renderLink, defaultContent }`.
+A legacy header node replaces the entire header; a callback supplies content
+inside its library-owned inset. Both footer forms retain SidebarFooter's rule and
+inset. Before/after navigation content scrolls with the links, so tall supporting
+content belongs there. Ordered `{ id, label?, items }` navigation groups supplement
+the Record form; use stable item IDs for branch state and live badges.
+renderItemContent changes noninteractive row content while preserving the owning
+link/disclosure/focus treatment; renderItem remains the full row escape hatch.
+Current matching selects the most-specific href; render contexts expose ancestor
+state separately from current active state. In icon mode, searchable
+AppSidebar preserves its search band as an icon button that expands and focuses
+the field without clearing the query. LayoutSidebarProvider defaults to
+comfortable rows with a shared xs gap. Default keeps that gap with smaller
+rows; compact uses a tighter 2xs gap. Caption and group spacing keep their own
+larger roles. Explicit density still wins.
 WorkspaceLayout owns its own bounded content inset; do not add a padded Page
 inside it. WorkspaceRecordHeader and WorkspaceLocaleStrip align to the same
 large inline surface role. Record copy supports textGap with a dense default.
@@ -502,3 +652,5 @@ formatted-value and structure owners. Drawn rings and mini charts retain private
 geometry and semantic chart/status colors. Read the
 [workflow contracts](workflows.md#task-summaries-usage-and-inline-editing) and
 [typed workspace recipe](../examples/planning-usage-edit.tsx) for integration.
+
+Explicit `type="display" inset="compact"` retains the small rich-surface tier (12px); collection compact insets use 8px. Display/default remains 24px. Chart tooltips and explicit small async previews retain their rich-content surface sizing.

package/docs/consumer-skill/references/critique-rubric.md

@@ -0,0 +1,98 @@
+# Critique rubric
+
+Use to judge a rendered view: after building one, before handing it back, or when
+reviewing someone else's screen. Judge screenshots and measurements, not source.
+Valid API usage, passing checks and a correct data model do not make a view
+clear.
+
+Render the view at 390×844 and 1440×900, in light and dark, with the states the
+task touches (opened menu or editor, error, accepted). Run the census below at
+each width, then score every criterion.
+
+## Criteria
+
+Score each criterion 0 (fails), 1 (partly) or 2 (passes). Criteria marked
+**blocking** must score 2 before the work is handed back.
+
+| # | Criterion | Question | How to measure |
+| --- | --- | --- | --- |
+| 1 | Five-second test (**blocking**) | From the first viewport alone, can you say what this is, what state it is in and what to do next? | Write the three answers from the screenshot before reading source. Compare them with the data brief's decision and facts |
+| 2 | Focal point | Is there one dominant element per view and per region, and is it the one the brief chose? | Look at a reduced screenshot; census `focalCandidates` lists the largest text and its position. The focal element is in the first viewport at both widths |
+| 3 | Hierarchy (**blocking**) | Does each region use at most three text levels, ordered title, value, supporting? | Census `regions[].textLevels`; above 4 needs a reason (a badge or a value primitive's secondary part). Compare `textStyles` outliers with their owners |
+| 4 | Emphasis budget | One solid primary command per page or surface; tones only where status changes the action? | Census `primaryCommands`: 0 means the next action has no emphasis, 2 or more on one surface means competition. Read each toned badge and name the status it states |
+| 5 | Data integrity (**blocking**) | Do figures, units, signs and totals match the records; zero and missing differ; nothing invented? | Check three figures against the data and recompute one total or delta |
+| 6 | Encoding fit | Does each chart answer a question you can write in one sentence, and does each table compare rows on shared columns? | Write the question beside each chart. Name the compared column for each table |
+| 7 | Grouping and rhythm | Do gaps grow from within a group to between groups to between sections, without filler or box-in-box? | Census `regions[].insideFrame` lists frames inside frames. Measure sibling gaps in the DOM; equal gaps at every level fail |
+| 8 | Alignment | Do peer regions share content start edges, and do numbers right-align on one axis? | Census `regions[].left` and `inset`: peers differ by at most 1px. A leading badge adds its own padding to `inset`; check it in the image |
+| 9 | Narrow reading order | At 390 wide, does the decision content come before evidence, with no sideways page scroll? | `overflowX` is 0. Scroll position of the focal element and the primary command. Tables may scroll inside their own region |
+| 10 | Theme and states | Does dark keep the same hierarchy and contrast, and are loading, empty, error and accepted states designed? | Dark screenshots of the same viewports; trigger each state the view supports |
+
+Hand back at 16 of 20 or more with every blocking criterion at 2. Otherwise fix
+the lowest-scoring criterion at its owner and score again. After three rounds,
+stop and report what remains and why.
+
+## Census
+
+Run in the page through the browser tool's JavaScript evaluation. It reads
+computed styles only and changes nothing.
+
+```js
+(() => {
+  const shown = el => { const r = el.getBoundingClientRect(); const s = getComputedStyle(el); return r.width > 0 && r.height > 0 && s.visibility !== 'hidden' && s.opacity !== '0'; };
+  const hasText = el => [...el.childNodes].some(node => node.nodeType === 3 && node.textContent.trim());
+  const words = el => (el.getAttribute('aria-label') || el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 40);
+  const probe = document.body.appendChild(Object.assign(document.createElement('span'), { style: 'background: var(--primary)' }));
+  const primary = getComputedStyle(probe).backgroundColor; probe.remove();
+  const all = [...document.querySelectorAll('body *')].filter(shown);
+  const texts = all.filter(hasText);
+  const style = el => { const s = getComputedStyle(el); return `${s.fontSize} ${s.fontWeight}`; };
+  const isFrame = el => { const s = getComputedStyle(el); const r = el.getBoundingClientRect();
+    return ['Top', 'Right', 'Bottom', 'Left'].every(side => parseFloat(s[`border${side}Width`]) > 0) && r.height >= 64 && r.width >= 160
+      && !el.matches('input, textarea, select, button, [role="combobox"], [role="group"]') && !el.querySelector('h1'); };
+  const frames = all.filter(isFrame);
+  const owner = el => frames.filter(frame => frame !== el && frame.contains(el)).at(-1);
+  const regions = frames.map(frame => {
+    const own = texts.filter(el => frame.contains(el) && owner(el) === frame);
+    const first = own[0];
+    return { region: first ? words(first) : '(no text)', top: Math.round(frame.getBoundingClientRect().top + scrollY), left: Math.round(frame.getBoundingClientRect().left),
+      inset: first ? Math.round(first.getBoundingClientRect().left - frame.getBoundingClientRect().left) : null,
+      textLevels: new Set(own.map(style)).size, insideFrame: owner(frame) ? words(texts.find(el => owner(frame).contains(el)) || owner(frame)) : null };
+  }).sort((a, b) => a.top - b.top || a.left - b.left);
+  const counts = new Map(texts.map(style).map(key => [key, 0]));
+  for (const el of texts) counts.set(style(el), counts.get(style(el)) + 1);
+  return {
+    viewport: `${innerWidth}x${innerHeight}`,
+    overflowX: document.documentElement.scrollWidth - document.documentElement.clientWidth,
+    primaryCommands: all.filter(el => el.matches('button, a') && getComputedStyle(el).backgroundColor === primary).map(words),
+    focalCandidates: texts.map(el => ({ el, size: parseFloat(getComputedStyle(el).fontSize) })).sort((a, b) => b.size - a.size).slice(0, 3).map(({ el, size }) => `${size}px ${words(el)} @${Math.round(el.getBoundingClientRect().top + scrollY)}`),
+    textStyles: [...counts].sort((a, b) => b[1] - a[1]).map(([key, count]) => `${key} ×${count}`),
+    regions,
+  };
+})()
+```
+
+The census lists signals, not verdicts. The application shell's frame (any frame
+containing the page `h1`) is excluded. Frames are bordered regions at least
+160×64px, so tables, cards and drawers appear. A surface without a border is not
+listed: judge it in the image.
+
+## Write findings
+
+One finding per problem, most severe first:
+
+```text
+[criterion #] <where: route, region, width/theme>
+Seen: <what the screenshot or census shows>
+Why it matters: <the user's decision or reading it harms>
+Fix: <owner and prop, or the content to remove or move>
+```
+
+A finding names the owner that should change. "Looks cluttered" is not a
+finding; "Purchased goods uses 9 text levels at 1440, so quantity, SKU and
+location compete with the product name" is.
+
+## Report the score
+
+State the score per criterion, with the measurement behind each 1 or 0, for
+every width and theme inspected. Say which states were not rendered: an
+unrendered state is unverified, not passed.