themelia-react-ui 1.0.0 → 1.0.2

package/docs/consumer-skill/SKILL.md

@@ -1,32 +1,126 @@
 ---
 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
 
-Start with [installed setup](references/installation.md): resolve the package from the app, check installed or copied guidance identity, and read version-matched declarations. Use [discovery](references/discovery.md) to find exact imports, symbols and responsibilities. The [public index](references/public-api.json) derives from actual exports and catalogue owners.
+Build from the public owner that fits the task. Use the exact family import,
+its supported props and the application's data, callbacks and product conventions.
+Before writing JSX, resolve the installed contract below. Select an owner in the
+table or finder, read its declaration and the matching recipe, then adapt the
+app's data/callbacks. Do not infer props or missing capabilities from names alone.
 
-Choose the smallest owner: typography for display roles, primitives for formatted values, base for controls/surfaces, layout for page regions, blocks for reusable presentation, features for interaction lifecycles. Routing, data, permissions, translation, storage and backend effects belong to the app.
+## Start with an owner
 
-Read only the relevant reference:
+| 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` |
+| 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` |
 
-- [Discovery](references/discovery.md): portable Node finder, selection metadata, optional peers and version-matched declarations.
-- [Installed setup](references/installation.md): package resolution, copied-skill freshness and manual installation.
-- [Composition](references/composition.md): card anatomy, responsive structures, spacing and menu/display ownership.
-- [Design contract](references/design-contract.md): application freedom, library-owned geometry, independent variants and enforcement limits.
-- [Integration](references/integration.md): installation, CSS, state, routing, overlays and verification.
-- [Theme extension](references/theming.md): compact tokens, scoped portals, radius and drift prevention.
-- [Generated tokens](references/tokens.json): current structural roots/defaults, advanced settings and utility vocabulary.
-- [Workflows](references/workflows.md): collection/navigation, detail, validated edit and destructive confirmation; callback ownership, optional peers and verification.
-- [Typed example](examples/composition.tsx): public-import composition verified against the packed package.
+For example, a KPI owns formatting, hierarchy and trend presentation:
 
-Prefer public props/slots and structures. Typography owns no margins; every gap/inset has one owner. rounded-radius is the default everywhere; rounded-inner is only for intentional nested bodies/items. Do not locally restyle control typography, height, corners or menu padding to hide a shared mismatch.
+```tsx
+import { Metric, MetricGrid, type MetricData } from 'themelia-react-ui/blocks/analytics';
+import { InlineStat, MetadataList } from 'themelia-react-ui/blocks/data-display';
 
-Use Card for headed content, including flat/no-padding composition inside an existing boundary. Choose PopoverMenu for routine searchable selection; type/inset belong to PopoverContent when custom anatomy is needed. Keep row density, control size, surface inset and title/description textGap independent; inspect the exact declaration before assigning a variant.
+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' },
+]} />;
+```
 
-Import themelia-react-ui/style.css once. Compiled component CSS requires no source scanning. Apps using semantic Tailwind classes also process theme.css with their own Tailwind v4 build. CSS owns appearance, UIProvider stable defaults, callbacks app state.
+`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 requires optional `recharts`, including without a sparkline;
+the focused UsageCard import has no chart peer. See [analytics](references/analytics.md).
 
-Async integrations must show real pending/failure/success and update data; a toast alone is not persistence. Use library overlays for modal workflows. Verify consuming-app types/tests/build and opened popovers, menus and tooltips in narrow/light/dark states.
+## Resolve the installed contract
 
-This skill ships with the package but is not installed automatically. No theme-publish/skill-install CLI exists. It grants no authorization to publish, deploy, message users or change other repositories.
+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.
+
+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
+```
+
+Task nouns retain richer alternatives; case-exact symbols such as `DataTable`
+and exact imports select their precise contract. Follow `relevantSymbols` and
+`nextReads` to the matching declaration, reference and recipe. Check the reported
+optional peers before assigning props. The [public index](references/public-api.json)
+contains all families; catalogue routes and private source paths are not imports.
+RichText accepts sanitized HTML; convert Markdown in the app before passing `html`.
+
+## Compose and adapt the screen
+
+Use Page for route identity/commands and Container/Section for content-led sites.
+Card frames one independent subject. Put status/count/version badges in
+`titleSuffix`, actions in `headerAction`/`actions`, and pre-title context in
+`headerStart`. Use `surface="flat" padding="none"` within an existing boundary.
+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. Use Heading/Text and formatted
+primitives for display copy; choose Heading `tag` for semantics and `size` for
+visual 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; keep per-component radius classes out of callers.
+Omit control size to inherit provider defaults. 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. A passing static check
+cannot establish that hierarchy, contrast, corners or spacing look right.
+Use CSS semantic surface/foreground pairs and existing structural roots for
+appearance; UIProvider supplies defaults. 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 |
+| --- | --- |
+| Structure, 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
+execute keyboard selection, dismissal/focus return, callbacks, validation and
+failure/retry. Keep source findings, inspected images and executed interactions
+separate; the optional checker reports errors, review warnings and unresolved
+expressions. Install/copy the complete skill manually after package upgrades.

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

@@ -4,28 +4,58 @@ 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>
+      headingTag: 'h1', actions: <Button onClick={onCreate}>Create record</Button> }}>
+    {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}} nav={<Stack direction="horizontal" gap="sm"><Button onClick={onCreate}>Create record</Button></Stack>}>{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

@@ -1,8 +1,9 @@
+import { Building2 } from 'lucide-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 { MetadataList } from 'themelia-react-ui/blocks/data-display';
 import { Date, Email, Money, Value } from 'themelia-react-ui/primitives';
-import { Text } from 'themelia-react-ui/typography';
+import { Page } from 'themelia-react-ui/layout/page';
 
 export interface AccountDetailRecord {
   id: string; name: string; email: string | null;
@@ -15,14 +16,28 @@ export interface AccountDetailProps {
 }
 
 export function AccountDetail({ account, onEdit, onBack }: AccountDetailProps) {
-  return <Card title={account.name} surface="card" headerPlacement="frame"
+  return <Card title={account.name} headerPlacement="frame"
     headerAction={<Button onClick={() => onEdit(account.id)}>Edit account</Button>}
     footerSlot={<Button tone="secondary" buttonStyle="outline" onClick={onBack}>Back to accounts</Button>}>
-    <Grid columns={{ base: 1, md: 2 }} gap="lg">
-      <Stack gap="xs"><Text type="secondary">Account ID</Text><Value>{account.id}</Value></Stack>
-      <Stack gap="xs"><Text type="secondary">Email</Text><Email value={account.email} /></Stack>
-      <Stack gap="xs"><Text type="secondary">Created</Text><Date value={account.createdAt} /></Stack>
-      <Stack gap="xs"><Text type="secondary">Balance</Text><Money amount={account.balanceMinor} currency={account.currency} unit="minor" /></Stack>
-    </Grid>
+    <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',actions:<Button onClick={()=>onEdit(account.id)}>Edit account</Button>}}>
+    <Card title="Contact and billing" icon={<Building2/>} 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" /> },
+    ]} />;
+}

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

@@ -1,6 +1,12 @@
 {
   "schemaVersion": 1,
   "examples": [
+    {
+      "file": "website.tsx",
+      "exports": ["WebsiteLandingPage"],
+      "phase": "basic",
+      "optionalPeers": []
+    },
     {
       "file": "composition.tsx",
       "exports": [
@@ -19,10 +25,16 @@
         "@tanstack/react-table"
       ]
     },
+    {
+      "file": "scoped-directory.tsx",
+      "exports": ["ScopedDirectory"],
+      "phase": "optional",
+      "optionalPeers": ["@tanstack/react-table", "react-day-picker"]
+    },
     {
       "file": "detail.tsx",
       "exports": [
-        "AccountDetail"
+        "AccountDetail", "AccountDetailPage"
       ],
       "phase": "basic",
       "optionalPeers": []
@@ -89,6 +101,20 @@
       ],
       "phase": "basic",
       "optionalPeers": []
+    },
+    {
+      "file": "planning-usage-edit.tsx",
+      "exports": [
+        "WorkspaceSummary"
+      ],
+      "phase": "basic",
+      "optionalPeers": []
+    },
+    {
+      "file": "analytics.tsx",
+      "exports": ["RevenueOverview", "RevenueMetric", "PlainStatistic"],
+      "phase": "optional",
+      "optionalPeers": ["recharts"]
     }
   ]
 }

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

@@ -0,0 +1,29 @@
+import { useState } from 'react';
+import { InlineEdit } from 'themelia-react-ui/base/inline-edit';
+import { Card } from 'themelia-react-ui/base/cards';
+import { AdaptiveGrid, Stack } from 'themelia-react-ui/base/structure';
+import { TaskCard, type TaskCardItem } from 'themelia-react-ui/blocks/planning';
+import { UsageCard, type UsageCardData } from 'themelia-react-ui/blocks/analytics/usage-card';
+
+/** The application supplies persistence, authoritative tasks and usage. */
+export function WorkspaceSummary({
+ initialName, tasks, usage, saveName, completeTask,
+}: {
+ initialName: string;
+ tasks: readonly TaskCardItem[];
+ usage: UsageCardData;
+ saveName: (name: string, signal: AbortSignal) => Promise<void>;
+ completeTask: (id: string, completed: boolean) => void;
+}) {
+ const [name, setName] = useState(initialName);
+ return <Stack gap="xl">
+  <Card title="Workspace">
+   <InlineEdit label="Project name" value={name} onValueChange={setName} required
+    onSave={(draft, {signal}) => saveName(draft, signal)} />
+  </Card>
+  <AdaptiveGrid minColumnWidth="md" gap="xl">
+   <TaskCard title="Release checklist" items={tasks} defaultExpanded onItemCompletedChange={completeTask} />
+   <UsageCard title="Workspace usage" data={usage} />
+  </AdaptiveGrid>
+ </Stack>;
+}

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

@@ -0,0 +1,77 @@
+import { useMemo, type ReactNode } from 'react';
+import { Button } from 'themelia-react-ui/base/buttons';
+import { Stack } from 'themelia-react-ui/base/structure';
+import { FilterLayout, FilterProvider, FilterType, type ActiveFilter, type FilterConfig } from 'themelia-react-ui/features/filters';
+import { DataTable, ResourceCell, type DataTableProps } from 'themelia-react-ui/features/table';
+import { Page } from 'themelia-react-ui/layout/page';
+import { Email } from 'themelia-react-ui/primitives';
+import { Text } from 'themelia-react-ui/typography';
+
+export interface DirectoryContact { id: string; name: string; role: string; email: string | null; }
+export type DirectoryState =
+  | { status: 'loading' }
+  | { status: 'error'; message: string }
+  | { status: 'ready'; records: DirectoryContact[] };
+export interface ScopedDirectoryProps {
+  scope: { id: string; label: string };
+  state: DirectoryState;
+  filters: ActiveFilter[];
+  onQueryChange: (query: { scopeId: string; filters: ActiveFilter[] }) => void;
+  onRetry: () => void;
+  onBack: () => void;
+  onCreate?: () => void;
+  onOpen: (id: string) => void;
+  exportAction?: ReactNode;
+  /** App chooses from available parent width; compact identity retains contact reach. */
+  compact?: boolean;
+  // Authoritative server pagination; the app preserves scope/query in its URLs.
+  pagination?: DataTableProps<DirectoryContact, unknown>['pagination'];
+  onPageChange?: DataTableProps<DirectoryContact, unknown>['onPageChange'];
+}
+const criteria: FilterConfig[] = [{
+  key: 'q', label: 'Search contacts', placeholder: 'Name, email or role',
+  type: FilterType.SEARCH, icon: null, operator: 'contains', delay: 0,
+  displayConfig: { display: 'always' },
+}];
+const columns: DataTableProps<DirectoryContact, unknown>['columns'] = [
+  { id: 'identity', header: 'Contact', cell: ({ row }) => <ResourceCell title={row.original.name}
+    subtitle={<Text size="xs" type="secondary">{row.original.role}</Text>} /> },
+  { accessorKey: 'email', header: 'Email', cell: ({ row }) => <Email value={row.original.email} /> },
+];
+const compactColumns: DataTableProps<DirectoryContact, unknown>['columns'] = [
+  { id: 'identity', header: 'Contact', cell: ({ row }) => <ResourceCell title={row.original.name}
+    subtitle={<Text size="xs" type="secondary">{row.original.role}</Text>}
+    metadata={<Email value={row.original.email} />} /> },
+];
+
+// Parent scope is navigation context, never a removable filter. The app loads
+// matching records. Its detail view keeps other operational facts available.
+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',
+    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,
+  }}>
+    <FilterProvider filters={criteria} activeFilters={props.filters}
+      navigating={props.state.status === 'loading'}
+      onFilterChange={filters => props.onQueryChange({ scopeId: props.scope.id,
+        // A cleared search can emit ['']; it is not an applied criterion here.
+        filters: filters.filter(filter => filter.key !== 'q' || filter.value.some(value => value.trim() !== '')),
+      })}>
+      <DataTable columns={props.compact ? compactColumns : columns} data={props.state.status === 'ready' ? props.state.records : []}
+        getRowId={contact => contact.id} enableSorting={false} enableColumnVisibility={false}
+        showFullscreenToggle={false} manualPagination pagination={props.state.status === 'ready' ? props.pagination : undefined} onPageChange={props.onPageChange}
+        topbarContent={<FilterLayout variant="compact" showClearFilters />} topbarEnd={props.exportAction}
+        emptyStateMessage={props.state.status === 'loading' ? 'Loading contacts…' :
+          props.state.status === 'error' ? 'Contacts could not be loaded.' :
+          props.filters.length ? 'No contacts match these criteria.' : 'No contacts in this business yet.'}
+        emptyStateAction={props.state.status === 'error' ? <Stack gap="dense"><Text role="alert" type="error">{props.state.message}</Text>
+          <Button tone="secondary" buttonStyle="outline" onClick={props.onRetry}>Retry contacts</Button></Stack> : undefined}
+        rowActions={rowActions} />
+    </FilterProvider>
+  </Page>;
+}

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>;
+}

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

@@ -0,0 +1,70 @@
+# Metrics and statistics
+
+Use this reference for dashboard KPIs, revenue overviews, statistic cards and
+usage summaries. The finder returns exact owners, relevant symbols and recipe
+reads; declarations establish the current props. These components present
+application data and never fetch or define a business metric.
+
+## Select the subject owner
+
+| Subject | Public owner | Frame and lifecycle |
+| --- | --- | --- |
+| One KPI with value, trend or sparkline | `Metric` from `themelia-react-ui/blocks/analytics` | `variant="card"` owns its Card; default/compact/minimal support lower-level composition. Has loading/error presentation. |
+| Peer dashboard KPIs or revenue figures | `MetricGrid` from `themelia-react-ui/blocks/analytics` | Defaults to card metrics; owns gaps and columns responding to its parent. `columns` is a maximum. Has loading, while error/retry/empty remain app-owned. |
+| Metrics sharing one strip and period action | `MetricBar` from `themelia-react-ui/blocks/analytics` | One strip from `MetricData[]`; period callback requests the current period value. App owns choosing/fetching periods and request states. |
+| Current versus previous metric | `MetricComparison` from `themelia-react-ui/blocks/analytics` | Uses current/previous `MetricData`; app defines the comparison baseline. |
+| Used/limit quotas with shares, daily values and period selection | `UsageCard` from `themelia-react-ui/blocks/analytics/usage-card` | Owns a Card and ready/loading/error/empty presentation with retry/period callbacks. No optional chart peer. |
+| One plain label/value fact | `InlineStat` from `themelia-react-ui/blocks/data-display` | Card-free; app chooses whether this subject needs a Card. |
+| Several facts about one record | `MetadataList` from `themelia-react-ui/blocks/data-display` | Card-free; value primitives own formatting. |
+| Caller-owned chart series | `ChartCard` from `themelia-react-ui/blocks/analytics` | Card-free chart composition; caller supplies chart content and an optional Card boundary. |
+
+Start with these subject owners before constructing a Card with a number and
+supporting text. Reuse their formatting, hierarchy and relevant states when
+the contract fits. A custom Card remains appropriate for a distinct subject
+or task with content/coordination these owners do not represent; keep their
+supported lower owners where useful. Do not put another Card around an owner
+that already renders its own surface.
+
+## Dashboard and revenue data
+
+[Analytics recipe](../examples/analytics.tsx) exports `RevenueOverview`,
+`RevenueMetric` and `PlainStatistic`. The overview accepts discriminated request
+state: loading renders MetricGrid skeletons, error replaces data with retry,
+and a ready empty array renders EmptyState. The parent supplies labels/IDs for
+loading metrics, accepts server data, executes retry and ignores stale results.
+It adds no implicit Card around the grid. The other exports show a standalone
+Metric and a plain factual InlineStat.
+
+`MetricData` requires stable `id`, `label` and `value`. Numeric currency values
+use `valueType="currency"` plus `currency`; pass major currency units, rather
+than a Money primitive's `unit="minor"` contract. Percentage values follow the
+shared formatter's ratio contract (0.12 renders 12%). `null` is unavailable;
+zero is real data. A string is already display data. `change.value` is caller
+copy, `change.direction` describes movement, and `trend` can override whether
+movement is positive, negative or neutral. A decline in churn can be positive.
+Keep the selected period and baseline clear in application context.
+
+`MetricGrid` forwards one `variant`, size and state recipe to its peers. Its
+default `gap="xl"` and Card insets remain independent from text/media `size`.
+Narrow parents reduce track count even on a wide viewport. Use `columns` and
+the public variants rather than overriding its internal grid, Card padding,
+value typography or sparkline geometry.
+
+The analytics family declaration/runtime graph requires the optional `recharts`
+peer even when a selected presentation hides its sparkline. Read the finder
+result's peers and installed declarations. UsageCard has a focused leaf import;
+its quota model differs from general MetricData.
+
+## Usage, facts and verification
+
+For `UsageCard` period/loading/error/retry and quota meaning, read
+[usage workflow](workflows.md#task-summaries-usage-and-inline-editing) and its
+[workspace summary recipe](../examples/planning-usage-edit.tsx).
+For record facts, choose MetadataList and primitives through the
+[detail recipe](../examples/detail.tsx), then decide Page and Card boundaries
+using [composition](composition.md#compose-from-the-task).
+
+Verify zero/unavailable values, loading/error/retry/empty, accepted period data,
+long labels/amounts, narrow parent widths and light/dark surfaces. Run the app's
+types and behavior checks; discovery and typechecking do not prove rendered
+geometry, keyboard callbacks or business-data correctness.