themelia-react-ui 1.0.1 → 2.0.0

package/docs/consumer-skill/SKILL.md

@@ -1,135 +1,139 @@
 ---
 name: themelia-react-ui-consumer
-description: Use when building, integrating, theming or migrating a React consuming app with themelia-react-ui, including admin pages, forms, layouts, blocks and workflows; not for library internals.
+description: Use when building, integrating, theming or migrating React apps and public websites with themelia-react-ui, including admin pages, forms, layouts and workflows; not for library internals.
 ---
 
 # Themelia React UI consumer
 
-Build application-specific screens from supported public owners. This skill
-routes the shipped references, indexes, recipes and read-only helpers; it is
-not an API replacement or a requirement to imitate one example layout.
+Build from the public owner that fits the task: resolve the installed contract,
+pick the exact family import in the table or finder, read its declaration and
+recipe, then adapt the app's data and callbacks. Never infer props from names.
+
+## House rules
+
+Each rule has an owning prop or component, and the [optional checker](references/review.md) warns on most; depart only for a nameable product reason.
+
+1. Mount `UIProvider` (`themelia-react-ui/ui-provider`) once at the app root; calls inherit its currency, locale, date, density, button, badge and card defaults.
+2. Give every admin route a `Page` (`themelia-react-ui/layout/page`); its title is the route's `h1`, so do not repeat it in the body.
+3. Give commands roles: one `header.primaryAction`, ordered `header.secondaryActions`, `destructive: true` plus `ConfirmDialog`. An untoned `Button` is the neutral outline; give only the main command `tone="primary"` (solid), one per page or surface.
+4. Space siblings with `Stack`/`Grid` and their semantic `gap` (`themelia-react-ui/base/structure`), not flex divs with gap or margin utilities.
+5. Write copy with `Heading`/`Text`, not raw `h1`–`h6`; show values with `Money`, `Date`, `Number` and `Percent`, and use `useMoneyFormatter()` inside strings.
+6. Color with semantic classes (`bg-muted`, `text-muted-foreground`, `border-border`, status tones); palette classes such as `bg-blue-500` bypass theming and dark mode.
+7. Badges stay neutral unless the status means `success`, `warning`, `destructive` or `info`. Titles, facts and rows get no decorative icons, and gaps, not dividers, separate a card's sections.
+8. In a Card, badges go in `titleSuffix`, one quick control in `headerAction`, a command list in `actions` and the commit action in `footerSlot`.
+9. Dialogs, confirmations, drawers and sheets come only from `themelia-react-ui/features/overlays` (`ActionDialog`, `ConfirmDialog`, `ActionDrawer` with `useOverlayVisibility`); never hand-roll a modal, import `Dialog`/`Sheet` primitives or add a modal library.
+
+## Start with an owner
+
+| Task | Exact import and starting symbols |
+| --- | --- |
+| KPI cards, revenue, trends, comparisons | `themelia-react-ui/blocks/analytics`: `Metric`, `MetricGrid`, `MetricBar`, `MetricComparison`, `MetricGradient`, `MetricMicroGrid`, `ChartCard`, `ActivityHeatmap` |
+| Used/limit quotas and period/retry states | `themelia-react-ui/blocks/analytics/usage-card`: `UsageCard` |
+| Record facts, one plain value, empty regions | `themelia-react-ui/blocks/data-display`: `MetadataList`, `InlineStat`, `EmptyState` |
+| Query-driven directory or tabular comparison | `themelia-react-ui/features/data-view`: `DataView`; `themelia-react-ui/features/table`: `DataTable`, `ResourceCell` |
+| Query criteria and facets | `themelia-react-ui/features/filters`: `FilterLayout`, `SelectFacet`, `SearchFacet`, `DateFacet` |
+| Modal action, confirmation, drawer | `themelia-react-ui/features/overlays`: `ActionDialog`, `ConfirmDialog`, `ActionDrawer`, `useOverlayVisibility` |
+| Fields, schema-driven forms, inline drafts | `themelia-react-ui/base/forms`: `FormField`, `FormSection`, `FormActionsBar`; `themelia-react-ui/features/schema-form`: `SchemaForm`; `themelia-react-ui/base/inline-edit`: `InlineEdit` |
+| Passive rows, stacks, tracks and spans | `themelia-react-ui/base/structure`: `Stack`, `Grid`, `GridCell`, `AdaptiveGrid`; a row is `Stack direction="horizontal"` |
+| Content measure, sections, main/aside split | `themelia-react-ui/layout/containers`: `Container`, `Section`, `TwoColumnLayout`, `PageViewport` |
+| Application shell, sidebar, route identity | `themelia-react-ui/layout/app-shell`: `AppLayout`; `themelia-react-ui/layout/sidebar`: `AppSidebar`; `themelia-react-ui/layout/page`: `Page` |
+| Public website and content sections | `themelia-react-ui/layout/containers`: `Container`, `Section`, `PageViewport` |
+| Task summaries and conversation messages | `themelia-react-ui/blocks/planning`: `TaskCard`; `themelia-react-ui/blocks/collaboration`: `Message`, `MessageBubble` |
+| Timelines, activity, commerce workflows | `themelia-react-ui/blocks/timelines`: `Timeline`, `StepsCard`; `themelia-react-ui/features/activities`: `ActivityLog`; discover the commerce subject below |
+| Money, dates, counts and contact values | `themelia-react-ui/primitives`: `Money`, `Date`, `DateTime`, `Number`, `Percent`, `Email`, `Phone` |
+| Display roles and sanitized rich HTML | `themelia-react-ui/typography`: `Heading`, `Text`, `DisplayLabel`, `Label`, `TextLink`; `themelia-react-ui/typography/rich-text`: `RichText` |
+
+For example, a KPI owns formatting, hierarchy and trend presentation:
+
+```tsx
+import { Metric, MetricGrid, type MetricData } from 'themelia-react-ui/blocks/analytics';
+import { InlineStat, MetadataList } from 'themelia-react-ui/blocks/data-display';
+
+const revenue: MetricData = {
+  id: 'revenue', label: 'Revenue', value: 42500,
+  valueType: 'currency', currency: 'USD',
+  change: { value: '+12%', direction: 'up' }, trend: 'positive',
+};
+export const Revenue = () => <Metric variant="card" data={revenue} />;
+export const Dashboard = () => <MetricGrid metrics={[revenue]} columns={3} />;
+export const InvoiceCount = () => <InlineStat label="Invoices" value={18} />;
+export const AccountFacts = () => <MetadataList items={[
+  { id: 'email', label: 'Email', value: 'morgan@example.com' },
+]} />;
+```
+
+`Metric variant="card"`, default `MetricGrid`, `UsageCard` and `TaskCard` already
+own their surfaces. MetadataList, InlineStat and ChartCard delegate framing;
+Receipt owns its flat paper and insets. Choose a custom subject when its content
+or lifecycle calls for it; reuse the appropriate lower owners within it. The analytics
+barrel needs optional `recharts`; UsageCard's focused import does not. See [analytics](references/analytics.md).
 
 ## Resolve the installed contract
 
-Start with [installed setup](references/installation.md). Resolve the package
-from the app, check installed/copied guidance identity, and read matching
-declarations. Refresh the complete skill after upgrades, including prose.
-Read current sibling pages and app adapters; keep local product policy separate.
+Follow [installed setup](references/installation.md) to resolve the app's package
+and check copied guidance after upgrades. Import `themelia-react-ui/style.css`
+once; shipped components need no source scanning. Apps authoring semantic
+utilities process `theme.css` in their Tailwind v4 build.
 
-Use [discovery](references/discovery.md) and the [public index](references/public-api.json)
-for exact imports, symbols, responsibilities, alternatives and optional peers.
-Search the task or exact symbol; shorten an empty query instead of guessing APIs.
-For conventional node_modules layouts, run from the app:
+For another task or an unfamiliar prop, run the bundled [finder](references/discovery.md):
 
 ```sh
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs record directory --limit 5
 ```
 
-Inspect the chosen declaration and its re-exports before assigning props.
-Prefer the focused published family; inspect optional peers for its whole-family
-types as well as runtime use. Catalogue URLs and private source are not imports.
-
-## Compose from the task
-
-Before JSX, identify fixed context, editable criteria, the user's next decision,
-leading information, command scope and required states. Keep this proportional
-to the task; ordinary edits do not need an approval ceremony or planning report.
-
-Choose the most complete existing owner whose lifecycle fits. Typography owns
-display roles; primitives own formatted values; base owns controls and surfaces;
-layout owns page regions; blocks own reusable subjects; features own workflows.
-Compose lower owners when a feature's coordination does not fit the product.
-
-Use Page for route identity and commands, Card for an independently framed subject,
-ResourceCell for table identity, Item for independent entries and MetadataList for
-facts about one subject. Compare DataView, DataTable and base Table by their actual
-query/selection/paging contracts. Keep fixed parent scope through query clearing.
-Use native table query, utility, bulk-action and row-action seams where they fit.
-
-Give commands explicit tone and page/collection/record scope. Card status/count
-badges use titleSuffix; headerStart is context, and actions use action slots.
-Prioritize identity and decision facts; preserve access to other facts through
-detail/disclosure rather than appending every hidden column to compact rows.
-Product-specific columns, form arrangements and richer rows remain app decisions.
-
-## Preserve structure, typography and appearance
-
-Assign each gap/inset once: shell/container owns gutters, surface owns padding,
-section owns rhythm, Stack/Grid owns sibling gaps, and typography owns no margins.
-Use public props/slots before adding local appearance overrides. A nested framed
-table or Card needs a distinct subject; use supported flat composition otherwise.
-
-Use shared Heading/Text/DisplayLabel/Label/TextLink roles and value primitives such
-as Money, Date and Email. Semantic element choice is separate from visual size.
-Primary row text stays at the shared default; compact supporting metadata uses
-the smaller secondary role. Density alone does not shrink primary content.
-Native editable text keeps its responsive control recipe. For rich HTML display
-use RichText; editing belongs to RichTextEditor. Preserve sanitization and scoped
-content rhythm; structural UI labels do not inherit prose margins.
-
-Keep copy textGap normal/dense, row density, control size and surface inset
-independent. Use gap-normal/gap-dense through the headed owner or Stack/Grid;
-avoid adding description margins. rounded-radius is the default, rounded-inner
-is for intentional nested regions. Do not replace control geometry/typography
-or anchored-region padding through classes, contentClassName or inline styles.
-PopoverMenu owns routine searchable selection; custom popups use public regions.
-
-## Integrate themes, layouts and workflows
-
-Import themelia-react-ui/style.css once; shipped components need no source scanning.
-Apps authoring semantic utilities process theme.css in their Tailwind v4 build.
-Keep broad resets in the lower-priority base layer. Retheme existing semantic
-surface/foreground pairs and structural roots; derived utilities are not new knobs.
-CSS owns appearance, UIProvider stable defaults, callbacks per-mount app state.
-Use ThemeScope for scoped portals, and native dir plus DirectionProvider for RTL.
-
-Reuse public shells/sidebars/headers. Constrain app-shell height and preserve one
-scroll owner, useful gutters, DOM/focus order and action wrapping. Check usable
-parent width as well as viewport width; embedded layouts may need container
-adaptation. Placement, alignment and overflow remain valid app-owned mechanics.
-
-Keep controlled values authoritative and accept callback proposals in the parent.
-Keep state mode fixed while mounted; choose explicit reset/remount behavior when
-the subject changes. Stabilize lifecycle-sensitive loader/schema/column inputs
-when their meaning is unchanged. The app owns routing, permissions, translation,
-transport, cancellation and persistence; use href/callback/render integration.
-
-Show relevant loading, empty, missing, error/retry, disabled, validation and success
-states. Preserve rejected drafts and ignore superseded results. A toast alone is
-not persistence; UI cancellation does not prove a server operation stopped.
-Use library overlays for modal workflows and their pending/dismissal contracts.
-Keep labels, field associations, icon-action names and translated strings meaningful.
-In server-component apps, mount interactive families from a client wrapper;
-use a family's published pure helpers where provided, without assuming SSR support.
-
-## Read the relevant detail and recipe
-
-| Task | Reference and example |
+Task nouns return richer alternatives; exact symbols such as `DataTable` and
+exact imports select one contract. Follow `relevantSymbols` and `nextReads`,
+check reported optional peers, and replace any name listed under `deprecated`.
+The [public index](references/public-api.json) lists all families; catalogue
+routes and source paths are not imports. RichText takes sanitized HTML, not Markdown.
+
+## Compose and adapt the screen
+
+Use Page for routes and Container/Section for content-led sites. Header `actions`
+holds non-command controls such as a period select, never command button rows.
+Card frames one independent subject; `headerStart` holds pre-title context and
+`surface="flat" padding="none"` composes within an existing boundary.
+For headed commerce/variants blocks, choose their `surface` prop instead of
+adding a second Card boundary; see [headed blocks](references/composition.md#headed-blocks-inside-surfaces).
+Use the table/query/selection/row-action seams when they fit the workflow.
+Keep fixed parent context while criteria change; make command scope clear.
+
+Give each inset and gap one owner: page/container gutters, surface padding,
+section rhythm and Stack/Grid sibling gaps. Peer Card stacks in TwoColumnLayout
+use `gap="2xl"` to match its default grid rhythm in both axes. Choose Heading
+`tag` for semantics and `size` for emphasis; keep typography margin-free and
+primary rows at the shared size. Choose `textGap`, density, control `size` and
+surface padding independently. Shells own global corners; controls/rows own
+bounded inner corners. Change `--radius` at the theme boundary, never per
+component. Public props and regions own internal anatomy; application
+placement, alignment and overflow remain flexible.
+
+Treat appearance feedback as an acceptance criterion: inspect the reported state
+and improve its owning composition or recipe, since a passing static check cannot
+show that hierarchy, contrast, corners or spacing look right. Theme through
+semantic pairs and structural roots; use ThemeScope for scoped portals and
+native `dir` plus DirectionProvider for RTL. See [theming](references/theming.md).
+
+Keep controlled values authoritative and per-mount callbacks in the component.
+The app owns routes, permissions, translation, transport and persistence. Preserve
+pending drafts and ignore superseded results; show loading, empty, error/retry,
+disabled and validation states. Use overlay focus/dismissal/pending contracts.
+For server-component apps, mount interactive families from a client wrapper.
+
+## Read the matching recipe and verify
+
+| Work | Focused guidance and complete example |
 | --- | --- |
-| Owner selection, Card, menu anatomy | [Composition](references/composition.md), [basic composition](examples/composition.tsx) |
-| Display roles, formatted values and rich HTML | [Typography and rich content](references/composition.md#typography-and-rich-content) |
-| Geometry ownership and independent variants | [Design contract](references/design-contract.md) |
-| CSS, providers, RTL, routers, async/editor integration | [Integration](references/integration.md) |
-| Theme roots, density, radius and portal inheritance | [Theming](references/theming.md), [generated tokens](references/tokens.json) |
-| Collection, fixed context, detail, edit and delete | [Workflows](references/workflows.md), [directory](examples/scoped-directory.tsx), [detail](examples/detail.tsx), [edit](examples/edit.tsx), [confirmation](examples/destructive-confirm.tsx) |
-| Application shells, navigation and parent adaptation | [Layout composition](references/composition.md#application-layouts), [workspace](examples/app-layout.tsx) |
-| TaskCard, UsageCard, InlineEdit and persistence | [Workflow contracts](references/workflows.md#task-summaries-usage-and-inline-editing), [summary](examples/planning-usage-edit.tsx) |
-| Email/templates, receipts, hierarchy/capture, files/messages | [Domain composition](references/composition.md#receipts), [all recipe exports and peers](examples/manifest.json) |
-| Whole-screen review and optional source checker | [Review and checks](references/review.md) |
-
-The manifest lists every runnable recipe, including ordinary/template emails,
-receipt, hierarchy/guided forms, message/files and the index table. Copy only the
-relevant recipe, adapt product labels/callbacks, and read its actual declarations.
-
-## Verify the integrated result
-
-Run the app's types/lint/tests/build. The optional check-composition.mjs script
-uses app TypeScript and checks direct imports/static anatomy; errors, warnings
-and unresolved expressions are distinct. It is not a full visual/accessibility audit.
-Separately inspect long copy, missing values, narrow/desktop and light/dark/RTL
-states. Open menus/overlays, execute callbacks and failure/retry, check keyboard
-selection/dismissal/focus return and reduced motion, and report unverified limits.
-
-This skill ships with the package and requires separate manual installation.
-No theme-publish/skill-install CLI exists. It grants no authorization to publish,
-deploy, message users or change other repositories.
+| Rows, grids, regions and peer gaps | [Layout-owner map](references/composition.md#structure-and-spacing), [layout blocks](examples/layout-blocks.tsx) |
+| Card, public websites, heading scale | [Composition](references/composition.md), [website](examples/website.tsx) |
+| Shell/sidebar/header and parent adaptation | [Layout composition](references/composition.md#application-layouts), [workspace](examples/app-layout.tsx) |
+| Directory, detail, editing and confirmation | [Workflows](references/workflows.md), [directory](examples/scoped-directory.tsx), [detail](examples/detail.tsx), [edit](examples/edit.tsx), [confirmation](examples/destructive-confirm.tsx) |
+| KPI, facts, quota/task summaries | [Analytics](references/analytics.md), [analytics recipe](examples/analytics.tsx), [task/usage/inline edit](examples/planning-usage-edit.tsx) |
+| Email, receipts, files, messages and integrations | [Domain composition](references/composition.md#receipts), [recipe exports/peers](examples/manifest.json), [integration](references/integration.md) |
+| Shared anatomy and source review | [Design contract](references/design-contract.md), [optional read-only checker](references/review.md) |
+
+Run the app's type/lint/behavior checks. Inspect long content and missing values
+at narrow/desktop parent widths in light/dark themes. Open menus/overlays and run
+keyboard selection, dismissal/focus return, callbacks, validation and retry. Keep
+source findings, inspected images and executed interactions separate; the checker
+reports errors, warnings and unresolved expressions. Recopy the skill on upgrade.

package/docs/consumer-skill/examples/analytics.tsx

@@ -0,0 +1,34 @@
+import { ErrorState, LoadingState } from 'themelia-react-ui/base/feedback';
+import { Metric, MetricGrid, type MetricData } from 'themelia-react-ui/blocks/analytics';
+import { EmptyState, InlineStat } from 'themelia-react-ui/blocks/data-display';
+
+export type RevenueOverviewState =
+  | { status: 'loading'; metrics: MetricData[] }
+  | { status: 'ready'; metrics: MetricData[] }
+  | { status: 'error'; message: string };
+
+/** The app owns accepted values, loading labels, requests and retry effects. */
+export function RevenueOverview({ state, onRetry }: {
+  state: RevenueOverviewState;
+  onRetry: () => void;
+}) {
+  if (state.status === 'error') {
+    return <ErrorState title="Revenue unavailable" description={state.message}
+      onRetry={onRetry} retryLabel="Retry revenue" />;
+  }
+  if (!state.metrics.length) {
+    return state.status === 'loading'
+      ? <LoadingState label="Loading revenue" />
+      : <EmptyState title="No revenue metrics" description="Choose a period with reported revenue." />;
+  }
+  return <MetricGrid metrics={state.metrics} columns={4} loading={state.status === 'loading'} />;
+}
+
+export function RevenueMetric({ data, loading = false }: { data: MetricData; loading?: boolean }) {
+  return <Metric data={data} variant="card" loading={loading} />;
+}
+
+/** A factual count has no comparison/trend semantics and owns no extra Card. */
+export function PlainStatistic({ invoices }: { invoices: number | null }) {
+  return <InlineStat label="Invoices" value={invoices} />;
+}

package/docs/consumer-skill/examples/app-layout.tsx

@@ -1,31 +1,59 @@
 import type { ReactNode } from 'react';
-import { Button } from 'themelia-react-ui/base/buttons';
 import { Card } from 'themelia-react-ui/base/cards';
 import { SidebarTrigger } from 'themelia-react-ui/base/sidebar';
-import { Stack } from 'themelia-react-ui/base/structure';
 import { AppLayout, type AppLayoutVariant } from 'themelia-react-ui/layout/app-shell';
+import { HeaderUserMenu, type HeaderUserMenuProps } from 'themelia-react-ui/layout/header';
 import { Page } from 'themelia-react-ui/layout/page';
-import { LayoutSidebarProvider } from 'themelia-react-ui/layout/sidebar';
+import { AppSidebar, LayoutSidebarProvider, SidebarNavigationUser, type AppSidebarProps } from 'themelia-react-ui/layout/sidebar';
+import type { UIConfig } from 'themelia-react-ui/ui-provider';
 import { Text } from 'themelia-react-ui/typography';
 
-/** Pass a public AppSidebar or app-owned navigation; routing remains app-owned. */
-export function WorkspaceLayout({ variant = 'inset', sidebar, onCreate }: {
+/** Use at the application's single UIProvider mount; CSS owns palette/geometry. */
+export const workspaceUIDefaults: UIConfig = {
+  density: { defaultScale: 'md' },
+  card: { defaultSurface: 'card', defaultHeaderDivider: true, defaultFooterDivider: true },
+};
+
+export interface WorkspaceLayoutProps {
   variant?: AppLayoutVariant;
-  sidebar: ReactNode;
+  /** Optional replacement for the assembled AppSidebar. */
+  sidebar?: ReactNode;
+  navigationGroups?: AppSidebarProps['navigationGroups'];
+  currentUrl?: string;
+  renderLink?: AppSidebarProps['renderLink'];
+  workspaceLinks?: AppSidebarProps['workspaceLinks'];
+  /** Custom pinned control; replaces the built-in workspace-link trigger. */
+  workspaceSwitcher?: ReactNode;
+  user?: HeaderUserMenuProps['user'];
+  onLogout?: () => void;
   onCreate: () => void;
-}) {
-  const content = <Page maxWidth="full" gutter={variant === 'stacked' ? 'none' : 'md'} className="py-surface"
+  narrow?: boolean;
+  children?: ReactNode;
+}
+
+/** The app accepts route/identity data and wires navigation/persistence callbacks. */
+export function WorkspaceLayout({ variant = 'inset', sidebar, navigationGroups = {},
+  currentUrl, renderLink, workspaceLinks, workspaceSwitcher, user, onLogout,
+  onCreate, narrow, children }: WorkspaceLayoutProps) {
+  const sidebarAccount = !sidebar && (variant === 'sidebar' || variant === 'inset');
+  const brand = <Text weight="semibold">Admin</Text>;
+  const account = user && !sidebarAccount ? <HeaderUserMenu user={user} onLogout={onLogout} /> : null;
+  const navigation = sidebar ?? <AppSidebar className="h-full" logo={brand} collapsedLogo={<Text>A</Text>}
+    currentUrl={currentUrl} renderLink={renderLink} navigationGroups={navigationGroups}
+    workspaceLinks={workspaceSwitcher ? undefined : workspaceLinks}
+    slots={{ headerEnd: workspaceSwitcher, footer: user && sidebarAccount ? <SidebarNavigationUser user={user} onLogout={onLogout} /> : undefined }} />;
+  const content = <Page narrow={narrow} gutter={variant === 'stacked' ? 'none' : undefined}
     header={{ title: 'Workspace', description: 'Review activity and manage your records.',
-      actions: <Button onClick={onCreate}>Create record</Button> }}>
-    <Card title="Activity"><Text>Application content goes here.</Text></Card>
+      primaryAction: { label: 'Create record', onClick: onCreate } }}>
+    {children ?? <Card title="Activity" footerText="Latest workspace activity"><Text>Application content goes here.</Text></Card>}
   </Page>;
-  const brand = <Text weight="semibold">Admin</Text>;
   const trigger = <SidebarTrigger />;
   return <LayoutSidebarProvider adaptTo="container" className="min-h-0">
     {variant === 'stacked' ? <AppLayout variant="stacked" className="h-svh min-h-0" logo={brand}
-      nav={<Stack direction="horizontal" gap="sm"><Button onClick={onCreate}>Create record</Button></Stack>}>{content}</AppLayout>
+      slots={{headerEnd: account}}>{content}</AppLayout>
       : variant === 'sidebar' || variant === 'inset' ? <AppLayout variant={variant} className="h-svh min-h-0"
-        sidebar={sidebar} sidebarTrigger={trigger} slots={{ toolbarStart: brand }}>{content}</AppLayout>
-      : <AppLayout variant={variant} className="h-svh min-h-0" logo={brand} sidebar={sidebar} sidebarTrigger={trigger}>{content}</AppLayout>}
+        sidebar={navigation} sidebarTrigger={trigger} slots={{ toolbarStart: brand, toolbarEnd: account }}>{content}</AppLayout>
+      : <AppLayout variant={variant} className="h-svh min-h-0" logo={brand} sidebar={navigation}
+        sidebarTrigger={trigger} slots={{headerEnd: account}}>{content}</AppLayout>}
   </LayoutSidebarProvider>;
 }

package/docs/consumer-skill/examples/detail.tsx

@@ -2,6 +2,7 @@ import { Button } from 'themelia-react-ui/base/buttons';
 import { Card } from 'themelia-react-ui/base/cards';
 import { MetadataList } from 'themelia-react-ui/blocks/data-display';
 import { Date, Email, Money, Value } from 'themelia-react-ui/primitives';
+import { Page } from 'themelia-react-ui/layout/page';
 
 export interface AccountDetailRecord {
   id: string; name: string; email: string | null;
@@ -14,14 +15,28 @@ export interface AccountDetailProps {
 }
 
 export function AccountDetail({ account, onEdit, onBack }: AccountDetailProps) {
-  return <Card title={account.name} surface="card" headerPlacement="frame"
-    headerAction={<Button onClick={() => onEdit(account.id)}>Edit account</Button>}
+  return <Card title={account.name} headerPlacement="frame"
+    headerAction={<Button tone="primary" onClick={() => onEdit(account.id)}>Edit account</Button>}
     footerSlot={<Button tone="secondary" buttonStyle="outline" onClick={onBack}>Back to accounts</Button>}>
-    <MetadataList columns={{ base: 1, md: 2 }} items={[
+    <AccountFacts account={account}/>
+  </Card>;
+}
+
+/** A focused resource route: Page owns measure, gutters, identity and commands. */
+export function AccountDetailPage({account,onEdit,onBack}:AccountDetailProps) {
+  return <Page narrow header={{title:account.name,description:'Account details',onBack,
+    backLabel:'Back to accounts',primaryAction:{label:'Edit account',onClick:()=>onEdit(account.id)}}}>
+    <Card title="Contact and billing" headerPlacement="frame">
+      <AccountFacts account={account}/>
+    </Card>
+  </Page>;
+}
+
+function AccountFacts({account}:{account:AccountDetailRecord}) {
+  return <MetadataList columns={{ base: 1, md: 2 }} items={[
       { id: 'id', label: 'Account ID', value: <Value>{account.id}</Value> },
       { id: 'email', label: 'Email', value: <Email value={account.email} /> },
       { id: 'created', label: 'Created', value: <Date value={account.createdAt} /> },
       { id: 'balance', label: 'Balance', value: <Money amount={account.balanceMinor} currency={account.currency} unit="minor" /> },
-    ]} />
-  </Card>;
+    ]} />;
 }

package/docs/consumer-skill/examples/edit.tsx

@@ -52,7 +52,7 @@ export function AccountEdit({ initial, onSave, onCancel }: AccountEditProps) {
         {error && <Text role="alert" type="error">{error}</Text>}
         {saved && <Text role="status">Account saved.</Text>}
         <Stack direction={{ base: 'vertical', sm: 'horizontal' }} gap="sm">
-          <Button type="submit" loading={pending} strings={{ loading: 'Saving account…' }}>Save account</Button>
+          <Button tone="primary" type="submit" loading={pending} strings={{ loading: 'Saving account…' }}>Save account</Button>
           <Button type="button" tone="secondary" buttonStyle="outline" disabled={pending} onClick={onCancel}>Cancel edit</Button>
         </Stack>
       </Stack>

package/docs/consumer-skill/examples/layout-blocks.tsx

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+import { Stack } from 'themelia-react-ui/base/structure';
+import { TwoColumnLayout } from 'themelia-react-ui/layout/containers';
+
+export interface LayoutBlocksProps {
+  summary?: ReactNode;
+  primary: ReactNode;
+  secondary: ReactNode;
+  support: ReactNode;
+  actions?: ReactNode;
+}
+
+/** Place inside Page. Pass independently framed subjects; this composition adds no Card or gutter. */
+export function LayoutBlocks({ summary, primary, secondary, support, actions }: LayoutBlocksProps) {
+  return <TwoColumnLayout adaptTo="container" header={summary}
+    main={<Stack gap="2xl">{primary}{secondary}</Stack>}
+    aside={<Stack gap="2xl">{support}</Stack>}
+    footer={actions ? <Stack direction="horizontal" justify="end" gap="md">{actions}</Stack> : undefined}
+  />;
+}

package/docs/consumer-skill/examples/manifest.json

@@ -1,6 +1,14 @@
 {
   "schemaVersion": 1,
   "examples": [
+    {
+      "file": "website.tsx",
+      "exports": [
+        "WebsiteLandingPage"
+      ],
+      "phase": "basic",
+      "optionalPeers": []
+    },
     {
       "file": "composition.tsx",
       "exports": [
@@ -21,14 +29,20 @@
     },
     {
       "file": "scoped-directory.tsx",
-      "exports": ["ScopedDirectory"],
+      "exports": [
+        "ScopedDirectory"
+      ],
       "phase": "optional",
-      "optionalPeers": ["@tanstack/react-table", "react-day-picker"]
+      "optionalPeers": [
+        "@tanstack/react-table",
+        "react-day-picker"
+      ]
     },
     {
       "file": "detail.tsx",
       "exports": [
-        "AccountDetail"
+        "AccountDetail",
+        "AccountDetailPage"
       ],
       "phase": "basic",
       "optionalPeers": []
@@ -103,6 +117,26 @@
       ],
       "phase": "basic",
       "optionalPeers": []
+    },
+    {
+      "file": "analytics.tsx",
+      "exports": [
+        "RevenueOverview",
+        "RevenueMetric",
+        "PlainStatistic"
+      ],
+      "phase": "optional",
+      "optionalPeers": [
+        "recharts"
+      ]
+    },
+    {
+      "file": "layout-blocks.tsx",
+      "exports": [
+        "LayoutBlocks"
+      ],
+      "phase": "basic",
+      "optionalPeers": []
     }
   ]
 }

package/docs/consumer-skill/examples/scoped-directory.tsx

@@ -50,11 +50,11 @@ export function ScopedDirectory(props: ScopedDirectoryProps) {
   const rowActions = useMemo<DataTableProps<DirectoryContact, unknown>['rowActions']>(() => [
     { id: 'open', label: 'Open contact', onClick: contact => props.onOpen(contact.id) },
   ], [props.onOpen]);
-  return <Page header={{ title: 'Contacts', headingTag: 'h1',
+  return <Page header={{ title: 'Contacts',
     description: 'People responsible for bookings, billing and operations.',
     onBack: props.onBack, backLabel: 'All businesses',
     slots: { beforeTitle: <Text type="secondary">Business: {props.scope.label}</Text> },
-    actions: props.onCreate ? <Button tone="primary" onClick={props.onCreate}>New contact</Button> : undefined,
+    primaryAction: props.onCreate ? { label: 'New contact', onClick: props.onCreate } : undefined,
   }}>
     <FilterProvider filters={criteria} activeFilters={props.filters}
       navigating={props.state.status === 'loading'}

package/docs/consumer-skill/examples/website.tsx

@@ -0,0 +1,56 @@
+import { useId } from 'react';
+import { Button } from 'themelia-react-ui/base/buttons';
+import { Card } from 'themelia-react-ui/base/cards';
+import { Grid, Stack } from 'themelia-react-ui/base/structure';
+import { Container, Section } from 'themelia-react-ui/layout/containers';
+import { Money, type MoneyValue } from 'themelia-react-ui/primitives';
+import { Heading, Text } from 'themelia-react-ui/typography';
+
+export interface ServiceOffer {
+  id: string;
+  title: string;
+  description: string;
+  price: MoneyValue;
+  priceNote: string;
+  href: string;
+  actionLabel: string;
+}
+
+/** Copy, prices, billing terms, destinations and site navigation belong to the app. */
+export function WebsiteLandingPage({ title, description, actionLabel, actionHref, servicesTitle, offers, locale }: {
+  title: string;
+  description: string;
+  actionLabel: string;
+  actionHref: string;
+  servicesTitle: string;
+  offers: readonly ServiceOffer[];
+  locale?: string;
+}) {
+  const introId = useId();
+  const servicesId = useId();
+  return <Container render={<main />} maxWidth="xl" className="py-surface-lg">
+    <Stack gap="2xl">
+      <Section aria-labelledby={introId}>
+        <Stack gap="normal">
+          <Heading tag="h1" size="4xl" id={introId}>{title}</Heading>
+          <Text type="secondary">{description}</Text>
+        </Stack>
+        <Stack direction="horizontal" gap="md">
+          <Button href={actionHref} tone="primary">{actionLabel}</Button>
+        </Stack>
+      </Section>
+      <Section aria-labelledby={servicesId}>
+        <Heading tag="h2" size="2xl" id={servicesId}>{servicesTitle}</Heading>
+        <Grid columns={{ base: 1, md: 2, lg: 3 }} gap="xl">
+          {offers.map(offer => <Card key={offer.id} title={offer.title} description={offer.description}
+            footerSlot={<Button href={offer.href} tone="secondary" buttonStyle="outline">{offer.actionLabel}</Button>}>
+            <Stack gap="dense">
+              <Money {...offer.price} locale={locale} align="left" weight="semibold" />
+              <Text type="secondary" size="xs">{offer.priceNote}</Text>
+            </Stack>
+          </Card>)}
+        </Grid>
+      </Section>
+    </Stack>
+  </Container>;
+}