themelia-react-ui 1.0.2 → 2.0.1

package/docs/consumer-skill/SKILL.md

@@ -5,11 +5,23 @@ description: Use when building, integrating, theming or migrating React apps and
 
 # Themelia React UI consumer
 
-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.
+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 [composition checker](references/review.md) reports 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`; the header renders `[secondary…] [primary] [⋯]`. Record headers in `features/resource`, `layout/workspace` and `layout/settings` take the same props. A record's sections go in `header.tabs`. 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
 
@@ -17,12 +29,15 @@ app's data/callbacks. Do not infer props or missing capabilities from names alon
 | --- | --- |
 | 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` |
+| Record facts, one plain value, empty regions | `themelia-react-ui/base/metadata-list`: `MetadataList`; `themelia-react-ui/blocks/data-display`: `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` |
+| Record page: status badge, role-based commands, section tabs with counts | `themelia-react-ui/layout/page`: `Page`, `PageHeaderAction`, `PageHeaderTabs`; see the [detail recipe](examples/detail.tsx) |
 | 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 |
@@ -33,7 +48,8 @@ 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';
+import { MetadataList } from 'themelia-react-ui/base/metadata-list';
+import { InlineStat } from 'themelia-react-ui/blocks/data-display';
 
 const revenue: MetricData = {
   id: 'revenue', label: 'Revenue', value: 42500,
@@ -43,24 +59,21 @@ const revenue: MetricData = {
 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' },
-]} />;
+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).
+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
 
-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.
+Follow [installed setup](references/installation.md) to resolve the package and check
+copied guidance after upgrades; paste the [project instructions block](references/agents-md.md)
+into the app's AGENTS.md. Import `themelia-react-ui/style.css` once; components need no
+source scanning. Apps authoring semantic utilities process `theme.css` with Tailwind v4.
 
 For another task or an unfamiliar prop, run the bundled [finder](references/discovery.md):
 
@@ -68,37 +81,36 @@ For another task or an unfamiliar prop, run the bundled [finder](references/disc
 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`.
+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 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 Page for routes and Container/Section for content-led sites. Header `actions`
+holds non-command controls such as a period select, never command rows. Card frames
+one subject; `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. 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
+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.
@@ -111,16 +123,16 @@ For server-component apps, mount interactive families from a client wrapper.
 
 | Work | Focused guidance and complete example |
 | --- | --- |
-| Structure, Card, public websites, heading scale | [Composition](references/composition.md), [website](examples/website.tsx) |
+| 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
-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.
+| Shared anatomy, checker and hand-back | [Design contract](references/design-contract.md), [composition checker](references/review.md#done-means) |
+
+Done means the [checker](references/review.md#done-means) reports no errors on the
+files you changed (fix and re-run, at most three rounds), then the app's typecheck,
+lint and tests pass. Inspect long content at narrow/desktop widths in light/dark;
+open menus/overlays and run keyboard, dismissal, validation and retry paths. Hand
+back each check as run or not run, and every kept warning with file:line.

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

@@ -1,8 +1,6 @@
 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';
@@ -13,7 +11,7 @@ import { Text } from 'themelia-react-ui/typography';
 /** 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 },
+  card: { defaultSurface: 'card' },
 };
 
 export interface WorkspaceLayoutProps {
@@ -46,13 +44,13 @@ export function WorkspaceLayout({ variant = 'inset', sidebar, navigationGroups =
     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.',
-      headingTag: 'h1', actions: <Button onClick={onCreate}>Create record</Button> }}>
+      primaryAction: { label: 'Create record', onClick: onCreate } }}>
     {children ?? <Card title="Activity" footerText="Latest workspace activity"><Text>Application content goes here.</Text></Card>}
   </Page>;
   const trigger = <SidebarTrigger />;
   return <LayoutSidebarProvider adaptTo="container" className="min-h-0">
     {variant === 'stacked' ? <AppLayout variant="stacked" className="h-svh min-h-0" logo={brand}
-      slots={{headerEnd: account}} 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={navigation} sidebarTrigger={trigger} slots={{ toolbarStart: brand, toolbarEnd: account }}>{content}</AppLayout>
       : <AppLayout variant={variant} className="h-svh min-h-0" logo={brand} sidebar={navigation}

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

@@ -17,9 +17,9 @@ export function AccountComposition({ save }: { save: (name: string) => Promise<v
   return <ThemeScope style={{ '--height-action': '2.5rem', '--height-control': '2.5rem' }}>
     <Grid columns={{ base: 1, lg: 2 }} align="start" gap="xl">
       <Card surface="card" title={savedName} titleSuffix={<Badge tone="neutral">Workspace</Badge>}
-        headerPlacement="frame" footerDivider
-        footerSlot={<Button tone="secondary" buttonStyle="outline" onClick={() => { setName(savedName); setError(undefined); editor.show(); }}>Edit workspace</Button>}>
-        <Stack gap="lg"><Text type="secondary">A framed header with one body and one footer.</Text></Stack>
+        headerPlacement="frame"
+        headerAction={<Button onClick={() => { setName(savedName); setError(undefined); editor.show(); }}>Edit workspace</Button>}>
+        <Stack gap="lg"><Text type="secondary">A framed header with one quick control and one body.</Text></Stack>
       </Card>
       <Card surface="flat" padding="none" title="Ownership">
         <Stack gap="md"><Text>The app owns data and save behavior.</Text>

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

@@ -1,13 +1,17 @@
-import { Building2 } from 'lucide-react';
+import { useState, type ReactNode } from '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 { MetadataList } from 'themelia-react-ui/base/metadata-list';
+import { ConfirmDialog, useOverlayVisibility } from 'themelia-react-ui/features/overlays';
+import { Page, type PageHeaderAction } from 'themelia-react-ui/layout/page';
 import { Date, Email, Money, Value } from 'themelia-react-ui/primitives';
-import { Page } from 'themelia-react-ui/layout/page';
+import { Text } from 'themelia-react-ui/typography';
 
 export interface AccountDetailRecord {
   id: string; name: string; email: string | null;
   createdAt: string | null; balanceMinor: number | null; currency: string;
+  /** Shown as the one status badge beside the title. */
+  overdue?: boolean;
 }
 export interface AccountDetailProps {
   account: AccountDetailRecord;
@@ -15,21 +19,63 @@ export interface AccountDetailProps {
   onBack: () => void;
 }
 
-export function AccountDetail({ account, onEdit, onBack }: AccountDetailProps) {
+/** One framed subject for a drawer or dashboard: one quick control, no page chrome. */
+export function AccountDetail({ account, onEdit }: AccountDetailProps) {
   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>}>
+    headerAction={<Button onClick={() => onEdit(account.id)}>Edit</Button>}>
     <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>
+export type AccountSection = 'overview' | 'invoices' | 'activity';
+
+export interface AccountDetailPageProps extends AccountDetailProps {
+  section: AccountSection;
+  onSectionChange: (section: AccountSection) => void;
+  invoiceCount: number;
+  onSendStatement: (id: string) => void;
+  /** Reject on failure; the confirmation stays open and shows the error. */
+  onDelete: (id: string) => Promise<void>;
+  /** The app's invoice table or activity log for the other sections. */
+  children?: ReactNode;
+}
+
+/**
+ * A record route: Page owns the title, status, commands and section tabs.
+ * Commands carry roles, not colours; the header places them.
+ */
+export function AccountDetailPage({ account, onEdit, onBack, section, onSectionChange,
+  invoiceCount, onSendStatement, onDelete, children }: AccountDetailPageProps) {
+  const deletion = useOverlayVisibility();
+  const [error, setError] = useState<string>();
+  const commands: PageHeaderAction[] = [
+    { label: 'Send statement', onClick: () => onSendStatement(account.id) },
+    { label: 'Delete account', destructive: true, onClick: () => { setError(undefined); deletion.show(); } },
+  ];
+  return <Page header={{
+    title: account.name, onBack, backLabel: 'Back to accounts',
+    titleBadges: account.overdue ? [{ label: 'Overdue', tone: 'warning' }] : undefined,
+    primaryAction: { label: 'Edit account', onClick: () => onEdit(account.id) },
+    secondaryActions: commands,
+    tabs: {
+      label: 'Account sections', value: section,
+      onValueChange: id => onSectionChange(id as AccountSection),
+      items: [
+        { id: 'overview', label: 'Overview' },
+        { id: 'invoices', label: 'Invoices', badge: invoiceCount },
+        { id: 'activity', label: 'Activity' },
+      ],
+    },
+  }}>
+    {section === 'overview'
+      ? <Card title="Contact and billing" headerPlacement="frame"><AccountFacts account={account}/></Card>
+      : children}
+    <ConfirmDialog {...deletion.overlayProps} destructive
+      title={`Delete ${account.name}?`} description="This permanently removes the account."
+      onAsyncConfirm={() => onDelete(account.id)}
+      onError={() => setError('Deletion failed. The account is kept; retry or cancel.')}>
+      {error && <Text role="alert" type="error">{error}</Text>}
+    </ConfirmDialog>
   </Page>;
 }
 

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

@@ -52,8 +52,8 @@ 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 type="button" tone="secondary" buttonStyle="outline" disabled={pending} onClick={onCancel}>Cancel edit</Button>
+          <Button tone="primary" type="submit" loading={pending} strings={{ loading: 'Saving account…' }}>Save account</Button>
+          <Button type="button" disabled={pending} onClick={onCancel}>Cancel edit</Button>
         </Stack>
       </Stack>
     </form>

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

@@ -3,7 +3,9 @@
   "examples": [
     {
       "file": "website.tsx",
-      "exports": ["WebsiteLandingPage"],
+      "exports": [
+        "WebsiteLandingPage"
+      ],
       "phase": "basic",
       "optionalPeers": []
     },
@@ -27,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", "AccountDetailPage"
+        "AccountDetail",
+        "AccountDetailPage"
       ],
       "phase": "basic",
       "optionalPeers": []
@@ -112,9 +120,23 @@
     },
     {
       "file": "analytics.tsx",
-      "exports": ["RevenueOverview", "RevenueMetric", "PlainStatistic"],
+      "exports": [
+        "RevenueOverview",
+        "RevenueMetric",
+        "PlainStatistic"
+      ],
       "phase": "optional",
-      "optionalPeers": ["recharts"]
+      "optionalPeers": [
+        "recharts"
+      ]
+    },
+    {
+      "file": "layout-blocks.tsx",
+      "exports": [
+        "LayoutBlocks"
+      ],
+      "phase": "basic",
+      "optionalPeers": []
     }
   ]
 }

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

@@ -1,5 +1,5 @@
 import { Receipt, ReceiptItems, type ReceiptLineItem } from 'themelia-react-ui/blocks/commerce/receipt';
-import { MetadataList } from 'themelia-react-ui/blocks/data-display';
+import { MetadataList } from 'themelia-react-ui/base/metadata-list';
 import { Money } from 'themelia-react-ui/primitives';
 import { Separator } from 'themelia-react-ui/base/display';
 import { Stack } from 'themelia-react-ui/base/structure';
@@ -13,7 +13,7 @@ export function PurchaseReceipt({ items, total, reference }: { items: readonly R
 			<Separator dashed />
 			<ReceiptItems items={items} currency="EUR" unit="minor" />
 			<Separator dashed />
-			<MetadataList layout="rows" items={[{ label: 'Total', value: <Money tag="div" className="block" amount={total} currency="EUR" unit="minor" weight="semibold" /> }]} />
+			<MetadataList layout="rows" valueAlign="end" items={[{ label: 'Total', value: <Money tag="div" className="block" amount={total} currency="EUR" unit="minor" weight="semibold" /> }]} />
 		</Stack>
 	</Receipt>;
 }

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'}
@@ -70,7 +70,7 @@ export function ScopedDirectory(props: ScopedDirectoryProps) {
           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}
+          <Button onClick={props.onRetry}>Retry contacts</Button></Stack> : undefined}
         rowActions={rowActions} />
     </FilterProvider>
   </Page>;

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

@@ -43,7 +43,7 @@ export function WebsiteLandingPage({ title, description, actionLabel, actionHref
         <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>}>
+            footerSlot={<Button href={offer.href}>{offer.actionLabel}</Button>}>
             <Stack gap="dense">
               <Money {...offer.price} locale={locale} align="left" weight="semibold" />
               <Text type="secondary" size="xs">{offer.priceNote}</Text>

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

@@ -0,0 +1,33 @@
+# Project instructions block
+
+Agents load a skill only when they decide to, and often never open it. Paste this
+block into the consuming app's `AGENTS.md`, which Codex, Cursor, Copilot and
+Claude Code read; in a project that has only `CLAUDE.md`, paste it there. It
+points agents at this installed skill and states when UI work is done.
+
+```md
+<!-- themelia-react-ui:start 2.0.1 -->
+## UI built with themelia-react-ui
+Before writing UI, read node_modules/themelia-react-ui/docs/consumer-skill/SKILL.md and the
+installed declarations; prefer them over memory. Find the owner for a task with:
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs <task nouns>
+Rules: one Page per route, whose title is the h1. Commands go in header.primaryAction
+(one) and ordered header.secondaryActions; destructive ones confirm with ConfirmDialog.
+A record's sections go in header.tabs. Space siblings with Stack/Grid gap; write copy
+with Heading/Text and values with Money/Date/Number; use semantic colors; badges stay
+neutral unless they state status; dialogs come only from themelia-react-ui/features/overlays.
+Done means: node node_modules/themelia-react-ui/docs/consumer-skill/scripts/check-composition.mjs <changed files>
+reports no errors (fix and re-run, at most three rounds), then the app's typecheck, lint
+and tests pass. Hand back each check as run or not run, and every kept warning with
+file:line and its reason.
+<!-- themelia-react-ui:end -->
+```
+
+- Keep the block between its markers and replace all of it after an upgrade. The
+  start marker records the package version it was generated for; app rules belong
+  outside the markers.
+- It names only the Node scripts that ship in `docs/consumer-skill/scripts`, so
+  every agent can run them without a plugin, MCP server or global CLI.
+- The done condition is the agent's, not the build's: app CI can stay
+  non-blocking on checker warnings. See [review](review.md#done-means) for the
+  hand-back and the checker's coverage.

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

@@ -15,7 +15,7 @@ application data and never fetch or define a business metric.
 | 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. |
+| Several facts about one record | `MetadataList` from `themelia-react-ui/base/metadata-list` | 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