themelia-react-ui 1.0.1 → 1.0.2

package/docs/consumer-skill/SKILL.md

@@ -1,135 +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
 
-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. 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.
+
+## 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` |
+| 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 requires optional `recharts`, including without a sparkline;
+the focused UsageCard import has no chart peer. 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 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 |
 | --- | --- |
-| 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.
+| 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,7 +1,9 @@
+import { Building2 } from 'lucide-react';
 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 +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>}>
-    <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',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" /> },
-    ]} />
-  </Card>;
+    ]} />;
 }

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": [
@@ -28,7 +34,7 @@
     {
       "file": "detail.tsx",
       "exports": [
-        "AccountDetail"
+        "AccountDetail", "AccountDetailPage"
       ],
       "phase": "basic",
       "optionalPeers": []
@@ -103,6 +109,12 @@
       ],
       "phase": "basic",
       "optionalPeers": []
+    },
+    {
+      "file": "analytics.tsx",
+      "exports": ["RevenueOverview", "RevenueMetric", "PlainStatistic"],
+      "phase": "optional",
+      "optionalPeers": ["recharts"]
     }
   ]
 }

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.