themelia-react-ui 2.0.3 → 2.0.5

package/docs/consumer-skill/agents/themelia-ui-designer.md

@@ -0,0 +1,96 @@
+---
+name: themelia-ui-designer
+description: Product designer for apps built with themelia-react-ui. Delegate a new view, a redesign, or a screen that works but reads poorly; it reads the real records, writes a view spec, builds with public owners, renders 390 and 1440 wide in light and dark, scores a critique rubric and fixes. Ask for review mode to get a read-only, independent critique of existing screens.
+model: inherit
+---
+
+# Themelia UI designer
+
+You are a product designer who builds. Your result is a view that lets its user
+decide quickly from real records, built with themelia-react-ui public owners and
+app markup over its tokens. You remove before you add, spend emphasis on
+purpose, and judge rendered screens rather than source.
+
+## Inputs
+
+The parent names the mode (`design` or `review`, default `design`), the routes
+or files, where the records live, the dev server URL when one runs, and any
+constraints. Ask the parent only when a decision depends on something the
+records, the brief and the code cannot tell you.
+
+## Load first
+
+- `node_modules/themelia-react-ui/docs/consumer-skills/themelia-design/SKILL.md`
+- `node_modules/themelia-react-ui/docs/consumer-skill/references/data-reading.md`
+- `node_modules/themelia-react-ui/docs/consumer-skill/references/view-spec.md`
+- `node_modules/themelia-react-ui/docs/consumer-skill/references/view-craft.md`
+- `node_modules/themelia-react-ui/docs/consumer-skill/references/critique-rubric.md`
+- `node_modules/themelia-react-ui/docs/consumer-skills/themelia-composition/SKILL.md`
+  for owners, surfaces and insets
+- The app's `AGENTS.md` or `CLAUDE.md`: its rules win over this file.
+
+## Design mode
+
+1. **Read the data.** Open the records (fixtures, mocks, types, API samples).
+   Read a typical, a large, an exceptional and an empty record. Write the data
+   brief.
+2. **Baseline.** If the view exists, render it and score the rubric before
+   changing anything. Keep these screenshots for the report.
+3. **Spec.** Write the view spec where the parent says, otherwise
+   `design/<view>.md`. Rank information, name the focal point, draw 390 and
+   1440 wireframes, choose an encoding per fact.
+4. **Owners.** Find and verify owners before JSX:
+   - `node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs <task nouns>`
+   - `node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --pattern record-detail|collection|edit|analytics --main <need> --aside <need>`
+   - `node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs <Symbol> --import <exact import> --prop <name>`
+   - `node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-tokens.mjs <role or root>`
+5. **One subject first.** Build one representative subject and render it at
+   both widths before repeating it.
+6. **Build the view.** Change only the app files in scope and new app
+   components. Never edit `node_modules` or the package.
+7. **Render.** Use the browser tool you have (built-in browser, Chrome or the
+   app's Playwright). Capture 390×844 and 1440×900 in light and dark, plus the
+   opened, error and accepted states the view supports. Wait for rendered state
+   instead of fixed delays. Run the rubric's census at each width.
+   Without a browser tool, stop here: return the render checklist (routes,
+   widths, themes, states) and mark appearance unverified. Never claim visual
+   quality without screenshots.
+8. **Critique.** Score the rubric as a reviewer who did not build the view.
+   Write findings in the rubric's format.
+9. **Fix.** Repair the lowest-scoring criterion at its owner, render again and
+   score again. Stop after three rounds and report what remains.
+10. **Check.** Run the app's typecheck, lint, tests and build, and
+    `node node_modules/themelia-react-ui/docs/consumer-skill/scripts/check-composition.mjs <changed files>`.
+    Execute the callbacks, validation, focus and error/retry paths your change
+    touched.
+
+## Review mode
+
+Read-only: do not edit files. Load the same references. Read the records and
+write your own data brief, render the routes and form your five-second answers
+before reading any design notes; then compare intent with result. Return the
+scores, findings and screenshots.
+
+## Rules
+
+- Real records only. No invented figures, trends or states; data gaps stay
+  visible and are reported.
+- Public imports only. No anatomy class overrides, new colours or tokens, blur,
+  decorative icons, filler cards or prose explaining the screen.
+- Do not add navigation, cards or commands because a prop allows them.
+- Keep existing behaviour: every command still works, explains why it is
+  disabled, or is removed with a reason.
+- Report a library limit by owner and prop with the workaround used.
+
+## Report
+
+1. Rubric scores before and after, per criterion, width and theme.
+2. Screenshot paths for each width, theme and state.
+3. The decisions that changed the view and why, including what was removed.
+4. Checks and interactions run, with results.
+5. Library gaps: owner, prop, workaround.
+6. Unverified: widths, themes, states or interactions not exercised.
+
+Keep measurements and screenshots separate from judgement: "the census shows 9
+text levels in Purchased goods" is evidence; "the view is clearer" is a claim
+that needs it.

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

@@ -3,8 +3,8 @@ import { Card } from 'themelia-react-ui/base/cards';
 import { SidebarTrigger } from 'themelia-react-ui/base/sidebar';
 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 { AppSidebar, LayoutSidebarProvider, SidebarNavigationUser, type AppSidebarProps } from 'themelia-react-ui/layout/sidebar';
+import { Page, type PageProps } from 'themelia-react-ui/layout/page';
+import { AppSidebar, LayoutSidebarProvider, SidebarNavigationUser, type AppSidebarProps, type LayoutSidebarProviderProps } from 'themelia-react-ui/layout/sidebar';
 import type { UIConfig } from 'themelia-react-ui/ui-provider';
 import { Text } from 'themelia-react-ui/typography';
 
@@ -26,15 +26,13 @@ export interface WorkspaceLayoutProps {
   workspaceSwitcher?: ReactNode;
   user?: HeaderUserMenuProps['user'];
   onLogout?: () => void;
-  onCreate: () => void;
-  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) {
+  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;
@@ -42,18 +40,81 @@ export function WorkspaceLayout({ variant = 'inset', sidebar, navigationGroups =
     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.',
-      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}}>{content}</AppLayout>
+      slots={{headerEnd: account}}>{children}</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>
+        sidebar={navigation} sidebarTrigger={trigger} slots={{ toolbarStart: brand, toolbarEnd: account }}>{children}</AppLayout>
       : <AppLayout variant={variant} className="h-svh min-h-0" logo={brand} sidebar={navigation}
-        sidebarTrigger={trigger} slots={{headerEnd: account}}>{content}</AppLayout>}
+        sidebarTrigger={trigger} slots={{headerEnd: account}}>{children}</AppLayout>}
+  </LayoutSidebarProvider>;
+}
+
+export interface WorkspaceRegionsLayoutProps {
+  /** Supply SidebarNavigationRail for a persistent area rail. */
+  primaryNavigation?: ReactNode;
+  sidebarPresentation?: 'panel' | 'rail';
+  navigationGroups?: AppSidebarProps['navigationGroups'];
+  contextualNavigationGroups?: AppSidebarProps['navigationGroups'];
+  /** Independent of shell/rail presentation: minimize to icons, hide, or stay expanded. */
+  contextualCollapsible?: AppSidebarProps['collapsible'];
+  /** A defined replacement wins over contextual groups; null removes the region. */
+  secondarySidebar?: ReactNode;
+  currentUrl?: string;
+  renderLink?: AppSidebarProps['renderLink'];
+  secondarySidebarWidth?: string;
+  openPanels?: LayoutSidebarProviderProps['openPanels'];
+  defaultOpenPanels?: LayoutSidebarProviderProps['defaultOpenPanels'];
+  onOpenPanelsChange?: LayoutSidebarProviderProps['onOpenPanelsChange'];
+  mobilePanel?: LayoutSidebarProviderProps['mobilePanel'];
+  onMobilePanelChange?: LayoutSidebarProviderProps['onMobilePanelChange'];
+  user?: HeaderUserMenuProps['user'];
+  onLogout?: () => void;
+  children?: ReactNode;
+}
+
+/** One provider coordinates the primary area and adjacent contextual navigation. */
+export function WorkspaceRegionsLayout({ primaryNavigation, sidebarPresentation = 'panel',
+  navigationGroups = {}, contextualNavigationGroups, contextualCollapsible = 'icon', secondarySidebar,
+  currentUrl, renderLink, secondarySidebarWidth,
+  openPanels, defaultOpenPanels = ['primary', 'secondary'], onOpenPanelsChange,
+  mobilePanel, onMobilePanelChange, user, onLogout, children }: WorkspaceRegionsLayoutProps) {
+  const hasContextualNavigation = secondarySidebar !== undefined
+    ? secondarySidebar != null && secondarySidebar !== false : contextualNavigationGroups !== undefined;
+  return <LayoutSidebarProvider adaptTo="container" className="min-h-0"
+    navigationPanel={hasContextualNavigation ? 'secondary' : 'primary'}
+    openPanels={openPanels} defaultOpenPanels={defaultOpenPanels} onOpenPanelsChange={onOpenPanelsChange}
+    mobilePanel={mobilePanel} onMobilePanelChange={onMobilePanelChange}>
+    <AppLayout variant="light-header" contentSurface="inset" className="h-svh min-h-0"
+      logo={<Text weight="semibold">Admin</Text>} sidebarTrigger={<SidebarTrigger />}
+      sidebarPresentation={sidebarPresentation}
+      mobileSidebarMode={sidebarPresentation === 'rail' ? 'inline' : 'drawer'}
+      secondarySidebarWidth={secondarySidebarWidth}
+      slots={{
+        headerEnd: user && <HeaderUserMenu user={user} onLogout={onLogout} />,
+        sidebar: primaryNavigation ?? <AppSidebar className="h-full" surface="transparent" menuDensity="comfortable"
+          navigationGroups={navigationGroups} currentUrl={currentUrl} renderLink={renderLink} />,
+        secondarySidebar: hasContextualNavigation ? secondarySidebar !== undefined ? secondarySidebar : <AppSidebar className="h-full" surface="transparent"
+          collapsible={contextualCollapsible} menuDensity="comfortable" searchable
+          navigationGroups={contextualNavigationGroups} currentUrl={currentUrl} renderLink={renderLink} /> : undefined,
+      }}>{children}</AppLayout>
   </LayoutSidebarProvider>;
 }
+
+export interface WorkspaceExamplePageProps {
+  onCreate: () => void;
+  narrow?: boolean;
+  /** Use none when a stacked/contained parent already owns the inline gutter. */
+  gutter?: PageProps['gutter'];
+  children?: ReactNode;
+}
+
+/** Illustrative route content; mount this or another route Page inside the shell. */
+export function WorkspaceExamplePage({ onCreate, narrow, gutter, children }: WorkspaceExamplePageProps) {
+  return <Page narrow={narrow} gutter={gutter}
+    header={{ title: 'Workspace', description: 'Review activity and manage your records.',
+      primaryAction: { label: 'Create record', onClick: onCreate } }}>
+    {children ?? <Card title="Activity" footerText="Latest workspace activity"><Text>Application content goes here.</Text></Card>}
+  </Page>;
+}

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

@@ -0,0 +1,77 @@
+import { useId, useRef, useState, type FormEvent } from 'react';
+import { Button } from 'themelia-react-ui/base/buttons';
+import { Checkbox } from 'themelia-react-ui/base/choice-inputs';
+import { FormField } from 'themelia-react-ui/base/forms';
+import { Stack } from 'themelia-react-ui/base/structure';
+import { Input, PasswordInput } from 'themelia-react-ui/base/text-inputs';
+import { AuthFooterLinks, AuthForm, AuthFormRow, AuthShell, type AuthShellProps } from 'themelia-react-ui/layout/auth';
+import { Text } from 'themelia-react-ui/typography';
+
+export interface PasswordSignInValue {
+  email: string;
+  password: string;
+  rememberDevice: boolean;
+}
+
+export interface PasswordSignInProps {
+  productName: string;
+  recoveryHref: string;
+  /** Optional public destination relevant to this sign-in flow. */
+  returnHref?: string;
+  renderLink?: AuthShellProps['renderLink'];
+  /** The app authenticates and navigates after success; reject on failure. */
+  onSignIn: (value: PasswordSignInValue) => Promise<void>;
+}
+
+export function PasswordSignIn({ productName, recoveryHref, returnHref, renderLink, onSignIn }: PasswordSignInProps) {
+  const id = useId();
+  const inFlight = useRef(false);
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [rememberDevice, setRememberDevice] = useState(false);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string>();
+
+  async function submit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (inFlight.current) return;
+    inFlight.current = true;
+    setError(undefined);
+    setPending(true);
+    try {
+      await onSignIn({ email, password, rememberDevice });
+    } catch {
+      setError('Sign-in failed. Check your details and try again.');
+    } finally {
+      inFlight.current = false;
+      setPending(false);
+    }
+  }
+
+  return <AuthShell brand={{ label: productName }} title="Sign in"
+    description="Use your account to continue." renderLink={renderLink}
+    footerLinks={returnHref ? [{ id: 'return', label: 'Return to application', href: returnHref }] : []}>
+    <AuthForm onSubmit={submit} aria-label="Password sign in" aria-busy={pending}>
+      <FormField label="Email" htmlFor={`${id}-email`} required>
+        <Input id={`${id}-email`} name="email" type="email" autoComplete="username"
+          required disabled={pending} value={email} onChange={event => setEmail(event.target.value)} />
+      </FormField>
+      <FormField label="Password" htmlFor={`${id}-password`} required>
+        <PasswordInput id={`${id}-password`} name="password" autoComplete="current-password"
+          required disabled={pending} value={password} onChange={event => setPassword(event.target.value)} />
+      </FormField>
+      <AuthFormRow>
+        <Stack render={<label htmlFor={`${id}-remember`} />} direction="horizontal" gap="md" wrap={false}>
+          <Checkbox id={`${id}-remember`} name="rememberDevice" checked={rememberDevice}
+            disabled={pending} onCheckedChange={checked => setRememberDevice(checked === true)} />
+          <Text tag="span">Remember this device</Text>
+        </Stack>
+        <AuthFooterLinks aria-label="Account recovery" renderLink={renderLink}
+          links={[{ id: 'recovery', label: 'Forgot password?', href: recoveryHref, disabled: pending }]} />
+      </AuthFormRow>
+      {error && <Text type="error" role="alert">{error}</Text>}
+      <Button tone="primary" type="submit" fullWidth loading={pending}
+        strings={{ loading: 'Signing in…' }}>Sign in</Button>
+    </AuthForm>
+  </AuthShell>;
+}

package/docs/consumer-skill/examples/commerce-lines.tsx

@@ -0,0 +1,271 @@
+import { CreditCard, FileText, Send } from 'lucide-react';
+import { Badge } from 'themelia-react-ui/base/badge';
+import { Card } from 'themelia-react-ui/base/cards';
+import { Alert, AlertDescription, AlertTitle } from 'themelia-react-ui/base/feedback';
+import { Stack } from 'themelia-react-ui/base/structure';
+import {
+	AddressCard,
+	AmountRow,
+	FulfillmentGroup,
+	InvoiceHeader,
+	InvoiceLineItems,
+	OrderCustomer,
+	OrderLineItem,
+	OrderSummary,
+	OrderTimeline,
+	OrderTransactions,
+	PaymentTimeline,
+	ShipmentTracking,
+	SummaryPanel,
+	type InvoiceColumn,
+	type InvoiceLineItem,
+} from 'themelia-react-ui/blocks/commerce';
+import { Page } from 'themelia-react-ui/layout/page';
+import { Money, Number as NumberValue } from 'themelia-react-ui/primitives';
+import { Text } from 'themelia-react-ui/typography';
+
+/** Mock accepted order values; the app owns tax, shipping and price calculations. */
+export function SoldProductWithSummary() {
+	return (
+		<Card title="Items and totals">
+			<Stack gap="xl">
+				<OrderLineItem
+					id="mug-sand-350"
+					title="Ceramic mug"
+					variantTitle="350 ml / Sand"
+					sku="MUG-350-SAND"
+					unitPrice="€18.00"
+					quantity={2}
+					total="€36.00"
+				/>
+				<SummaryPanel>
+					<AmountRow label="Subtotal" amount="€36.00" />
+					<AmountRow label="Shipping" amount="€6.50" />
+					<AmountRow label="Tax" note="20%" amount="€8.50" />
+					<AmountRow label="Grand total" amount="€51.00" total rollup />
+				</SummaryPanel>
+			</Stack>
+		</Card>
+	);
+}
+
+/** Custom JSX values keep their roles: quiet regular breakdown, bold financial total. */
+export function CustomServiceInvoice() {
+	// Custom columns replace the default four-column/mobile recipe with this two-column grid.
+	const serviceColumns: InvoiceColumn<InvoiceLineItem>[] = [
+		{
+			id: 'service',
+			header: 'Service',
+			width: 'minmax(0, 1fr)',
+			cell: (item) => (
+				<Stack gap="xs">
+					<Text type="inherit" className="wrap-anywhere">{item.description}</Text>
+					<Text tag="span" size="xs" type="secondary">
+						<NumberValue value={item.qty} /> × <Money amount={item.price} currency="EUR" />
+					</Text>
+				</Stack>
+			),
+		},
+		{
+			id: 'line-total',
+			header: 'Line total',
+			width: 'max-content',
+			align: 'right',
+			cell: (item) => <Money type="inherit" amount={item.total} currency="EUR" weight="regular" />,
+		},
+	];
+
+	return (
+		<InvoiceLineItems
+			items={[
+				{ description: 'Design services', qty: 1, price: 335, total: 335 },
+				{ description: 'Research workshop', qty: 2, price: 380, total: 760 },
+				{ description: 'Implementation support', qty: 3, price: 425, total: 1275 },
+			]}
+			columns={serviceColumns}
+			footerRows={[
+				{ label: 'Subtotal', value: <Money type="inherit" amount={2370} currency="EUR" weight="regular" /> },
+				{ label: 'VAT (20%)', value: <Money type="inherit" amount={474} currency="EUR" weight="regular" /> },
+				// emphasis controls the label/spacing; this React-node value owns its weight.
+				{ label: 'Invoice total', value: <Money type="inherit" amount={2844} currency="EUR" weight="bold" />, emphasis: 'total' },
+			]}
+		/>
+	);
+}
+
+export interface OrderFulfillmentDetailProps {
+	/** Requests fulfillment of the open group; the app accepts and reloads the order. */
+	onFulfill: () => void;
+	onPrintPackingSlip: () => void;
+	/** Opens the app's refund workflow, for example in an ActionDrawer. */
+	onRefund: () => void;
+}
+
+/**
+ * One order route: Page owns the heading and commands, each subject is framed
+ * once, and the buyer and payment ledger sit in the aside. Mock accepted values.
+ */
+export function OrderFulfillmentDetail({ onFulfill, onPrintPackingSlip, onRefund }: OrderFulfillmentDetailProps) {
+	return (
+		<Page
+			header={{
+				title: 'Order #1042',
+				slots: { titleSuffix: <><Badge tone="warning">Partially fulfilled</Badge><Badge tone="success">Paid</Badge></> },
+				primaryAction: { label: 'Fulfill items', onClick: onFulfill },
+				secondaryActions: [{ label: 'Print packing slip', onClick: onPrintPackingSlip }, { label: 'Refund', onClick: onRefund }],
+			}}
+			aside={(
+				<>
+					<OrderCustomer
+						surface="card"
+						name="Ava Chen"
+						email="ava.chen@example.com"
+						orderCount={4}
+						shippingAddress={{ name: 'Ava Chen', line1: '18 Ermou Street', city: 'Athens', postalCode: '105 63', country: 'Greece' }}
+						billingSameAsShipping
+					/>
+					<OrderSummary
+						surface="card"
+						goods={[{ label: 'Subtotal', amount: '€104.00' }, { label: 'Shipping', amount: '€6.50' }]}
+						total={{ label: 'Total', amount: '€110.50' }}
+						payments={[{ label: 'Paid by card', amount: '€110.50' }]}
+						paymentStatus="paid"
+					/>
+					<OrderTransactions
+						surface="card"
+						transactions={[
+							{ id: 'auth', kind: 'authorization', status: 'success', amount: '€110.50', processedAt: '12 Oct, 09:14', method: 'Visa •••• 4242' },
+							{ id: 'capture', kind: 'capture', status: 'success', amount: '€110.50', processedAt: '12 Oct, 09:15', reference: 'ch_3PqL2x' },
+						]}
+					/>
+				</>
+			)}
+		>
+			<Alert tone="warning">
+				<AlertTitle>Confirm the delivery address</AlertTitle>
+				<AlertDescription>The courier flagged the postal code; confirm it with the customer before the Athens parcel ships.</AlertDescription>
+			</Alert>
+			<FulfillmentGroup
+				status="unfulfilled"
+				location="Athens warehouse"
+				items={[{ id: 'shirt', title: 'Linen overshirt', variantTitle: 'Navy / M', sku: 'LIN-OVR-NVY-M', unitPrice: '€68.00', quantity: 1, total: '€68.00' }]}
+				actions={[{ id: 'fulfill', label: 'Fulfill items', onClick: onFulfill }, { id: 'slip', label: 'Print packing slip', onClick: onPrintPackingSlip }]}
+			/>
+			<FulfillmentGroup
+				status="fulfilled"
+				location="Thessaloniki store"
+				items={[{ id: 'mug', title: 'Stoneware mug', variantTitle: 'Salt', sku: 'MUG-STW-SALT', unitPrice: '€18.00', quantity: 2, total: '€36.00' }]}
+			/>
+			<ShipmentTracking
+				surface="card"
+				carrier="ACS Courier"
+				trackingNumber="7781 2290 114"
+				status="in_transit"
+				steps={[
+					{ label: 'Label created', done: true, timestamp: '12 Oct, 11:02' },
+					{ label: 'Picked up', done: true, timestamp: '12 Oct, 16:40' },
+					{ label: 'Out for delivery', done: false },
+					{ label: 'Delivered', done: false },
+				]}
+			/>
+			{/* OrderTimeline owns its title; the Card only frames it. */}
+			<Card>
+				<OrderTimeline
+					title="History"
+					events={[
+						{ id: 'placed', title: 'Order placed', timestamp: '12 Oct, 09:14', status: 'completed' },
+						{ id: 'shipped', title: 'Mugs shipped from Thessaloniki', timestamp: '12 Oct, 16:40', status: 'completed' },
+						{ id: 'athens', title: 'Overshirt awaiting fulfillment', timestamp: 'Now', status: 'current' },
+					]}
+				/>
+			</Card>
+		</Page>
+	);
+}
+
+export interface ReceivableInvoiceDetailProps {
+	onRecordPayment: () => void;
+	onSendReminder: () => void;
+	onApplyCredit: () => void;
+	onExportPdf: () => void;
+}
+
+/**
+ * One invoice route: the document Card is the only frame around its header,
+ * flat line items and ledger; settlement and history are separate subjects.
+ * Long secondary labels stay in the More actions menu beside the primary command.
+ */
+export function ReceivableInvoiceDetail({ onRecordPayment, onSendReminder, onApplyCredit, onExportPdf }: ReceivableInvoiceDetailProps) {
+	return (
+		<Page
+			header={{
+				title: 'INV-2026-118',
+				slots: { titleSuffix: <Badge tone="destructive">Overdue</Badge> },
+				primaryAction: { label: 'Record payment', onClick: onRecordPayment },
+				secondaryActions: [
+					{ label: 'Send reminder', onClick: onSendReminder },
+					{ label: 'Apply approved credit', onClick: onApplyCredit },
+					{ label: 'Export PDF', onClick: onExportPdf },
+				],
+				maxVisibleSecondaryActions: 1,
+			}}
+			aside={(
+				<>
+					<Card title="Settlement">
+						<SummaryPanel>
+							<AmountRow label="Invoice total" amount="€2,199.76" />
+							<AmountRow label="Bank transfer, 14 Oct" amount="€1,000.00" deduction />
+							<AmountRow label="Balance due" amount="€1,199.76" total rollup />
+						</SummaryPanel>
+					</Card>
+					<AddressCard
+						surface="card"
+						kind="billing"
+						name="Kalliope Studio IKE"
+						line1="42 Tsimiski Street"
+						city="Thessaloniki"
+						postalCode="546 23"
+						country="Greece"
+					/>
+				</>
+			)}
+		>
+			<Card>
+				<Stack gap="2xl">
+					<InvoiceHeader
+						invoiceNumber="INV-2026-118"
+						status="overdue"
+						from={{ name: 'Ledgerline Accounting', location: 'Athens' }}
+						to={{ name: 'Kalliope Studio IKE', location: 'Thessaloniki' }}
+						issuedDate="12 Oct 2026"
+						dueDate="26 Oct 2026"
+						amount="€1,199.76"
+					/>
+					<InvoiceLineItems
+						surface="flat"
+						currency="EUR"
+						items={[
+							{ description: 'Quarterly bookkeeping retainer, July to September 2026', qty: 1, price: 1275, total: 1275 },
+							{ description: 'Payroll processing (per employee)', qty: 14, price: 18.5, total: 259 },
+							{ description: 'VAT return preparation', qty: 1, price: 240, total: 240 },
+						]}
+						footerRows={[
+							{ label: 'Subtotal', value: <Money type="inherit" amount={1774} currency="EUR" weight="regular" /> },
+							{ label: 'VAT (24%)', value: <Money type="inherit" amount={425.76} currency="EUR" weight="regular" /> },
+							{ label: 'Invoice total', value: <Money type="inherit" amount={2199.76} currency="EUR" weight="bold" />, emphasis: 'total' },
+						]}
+					/>
+				</Stack>
+			</Card>
+			<Card title="Payment history">
+				<PaymentTimeline
+					events={[
+						{ label: 'Invoice issued', date: '12 Oct', icon: FileText, done: true },
+						{ label: 'Partial payment received', date: '14 Oct', amount: '€1,000.00', icon: CreditCard, done: true },
+						{ label: 'Reminder due', date: '28 Oct', icon: Send, done: false },
+					]}
+				/>
+			</Card>
+		</Page>
+	);
+}

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

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+import { Stack } from 'themelia-react-ui/base/structure';
+import { InlineStat } from 'themelia-react-ui/blocks/data-display';
+import { Money } from 'themelia-react-ui/primitives';
+
+/** Card-free app content: its parent owns the subject title and any surface. */
+export function AssessmentComparison({declared, assessed, currency, labels, actions}: {
+  declared: number;
+  assessed: number;
+  currency: string;
+  labels: {declared: string; assessed: string};
+  actions?: ReactNode;
+}) {
+  return <Stack gap="xl" className="@container min-w-0">
+    <div className="grid min-w-0 grid-cols-1 gap-space-xl @lg:grid-cols-2">
+      <InlineStat layout="stacked" label={labels.declared} value={<Money amount={declared} currency={currency} />} />
+      <InlineStat layout="stacked" label={labels.assessed} value={<Money amount={assessed} currency={currency} />} />
+    </div>
+    {actions && <Stack direction="horizontal" justify="end" gap="md">{actions}</Stack>}
+  </Stack>;
+}

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

@@ -1,4 +1,5 @@
 import { useState, type ReactNode } from 'react';
+import { Badge } from 'themelia-react-ui/base/badge';
 import { Button } from 'themelia-react-ui/base/buttons';
 import { Card } from 'themelia-react-ui/base/cards';
 import { MetadataList } from 'themelia-react-ui/base/metadata-list';
@@ -21,7 +22,7 @@ export interface 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"
+  return <Card title={account.name}
     headerAction={<Button onClick={() => onEdit(account.id)}>Edit</Button>}>
     <AccountFacts account={account}/>
   </Card>;
@@ -52,9 +53,9 @@ export function AccountDetailPage({ account, onEdit, onBack, section, onSectionC
     { label: 'Send statement', onClick: () => onSendStatement(account.id) },
     { label: 'Delete account', destructive: true, onClick: () => { setError(undefined); deletion.show(); } },
   ];
-  return <Page header={{
+  return <Page narrow header={{
     title: account.name, onBack, backLabel: 'Back to accounts',
-    titleBadges: account.overdue ? [{ label: 'Overdue', tone: 'warning' }] : undefined,
+    slots: { titleSuffix: account.overdue ? <Badge tone="warning">Overdue</Badge> : null },
     primaryAction: { label: 'Edit account', onClick: () => onEdit(account.id) },
     secondaryActions: commands,
     tabs: {
@@ -68,7 +69,7 @@ export function AccountDetailPage({ account, onEdit, onBack, section, onSectionC
     },
   }}>
     {section === 'overview'
-      ? <Card title="Contact and billing" headerPlacement="frame"><AccountFacts account={account}/></Card>
+      ? <Card title="Contact and billing"><AccountFacts account={account}/></Card>
       : children}
     <ConfirmDialog {...deletion.overlayProps} destructive
       title={`Delete ${account.name}?`} description="This permanently removes the account."