themelia-react-ui 2.0.5 → 3.0.0

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

@@ -47,12 +47,13 @@ const compactColumns: DataTableProps<DirectoryContact, unknown>['columns'] = [
 // Parent scope is navigation context, never a removable filter. The app loads
 // matching records. Its detail view keeps other operational facts available.
 export function ScopedDirectory(props: ScopedDirectoryProps) {
+  const { onOpen } = props;
   const rowActions = useMemo<DataTableProps<DirectoryContact, unknown>['rowActions']>(() => [
-    { id: 'open', label: 'Open contact', onClick: contact => props.onOpen(contact.id) },
-  ], [props.onOpen]);
+    { id: 'open', label: 'Open contact', onClick: contact => onOpen(contact.id) },
+  ], [onOpen]);
   return <Page header={{ title: 'Contacts',
     description: 'People responsible for bookings, billing and operations.',
-    onBack: props.onBack, backLabel: 'All businesses',
+    onBack: props.onBack, strings: { back: 'All businesses' },
     slots: { beforeTitle: <Text type="secondary">Business: {props.scope.label}</Text> },
     primaryAction: props.onCreate ? { label: 'New contact', onClick: props.onCreate } : undefined,
   }}>
@@ -64,11 +65,11 @@ export function ScopedDirectory(props: ScopedDirectoryProps) {
       })}>
       <DataTable columns={props.compact ? compactColumns : columns} data={props.state.status === 'ready' ? props.state.records : []}
         getRowId={contact => contact.id} enableSorting={false} enableColumnVisibility={false}
-        showFullscreenToggle={false} manualPagination pagination={props.state.status === 'ready' ? props.pagination : undefined} onPageChange={props.onPageChange}
+        showFullscreenToggle={false} pagination={props.state.status === 'ready' ? props.pagination : undefined} onPageChange={props.onPageChange}
         topbarContent={<FilterLayout variant="compact" showClearFilters />} topbarEnd={props.exportAction}
-        emptyStateMessage={props.state.status === 'loading' ? 'Loading contacts…' :
+        strings={{ emptyState: { message: props.state.status === 'loading' ? 'Loading contacts…' :
           props.state.status === 'error' ? 'Contacts could not be loaded.' :
-          props.filters.length ? 'No contacts match these criteria.' : 'No contacts in this business yet.'}
+          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 onClick={props.onRetry}>Retry contacts</Button></Stack> : undefined}
         rowActions={rowActions} />

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

@@ -3,35 +3,39 @@
 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.
+points agents at this installed skill and states when UI work is done. Print it
+with `node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --agents-block`;
+nothing writes it into the app for you.
 
 ```md
-<!-- themelia-react-ui:start 2.0.5 -->
+<!-- themelia-react-ui:start 3.0.0 -->
 ## UI built with themelia-react-ui
-Read the matching node_modules/themelia-react-ui/docs/consumer-skills/<name>/SKILL.md:
-themelia-components: setup, discovery and typed APIs/forms;
-themelia-tokenization: semantic themes, visual roles and portals;
-themelia-composition: data-led subjects, hierarchy, responsive regions and repair;
-themelia-design: data briefs, view specs, scored critique.
-Read installed declarations. Shared assets/agent: docs/consumer-skill.
-Decide task, hierarchy, action priority and surface/inset owners before JSX:
-node_modules/themelia-react-ui/docs/consumer-skill/references/screen-decisions.md.
-Find domain owners/public parts; compare APIs before custom markup:
-node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs <task nouns>
+Simple views are 100% Themelia owners. Domain views are ~70% owners; the rest
+is app-owned subjects made from Themelia parts and tokens. Never hand-roll
+what it ships. Read first, under
+node_modules/themelia-react-ui/docs/consumer-skill/references/:
+building-views.md (reach order, need → owner, the custom part), catalogue.md
+(every component), screen-decisions.md (task, subject, scopes, insets).
+Props: read dist/**/*.d.ts of the chosen import; never the package src/.
+Skills: node_modules/themelia-react-ui/docs/consumer-skills/<name>/SKILL.md:
+themelia-components: setup/APIs/forms; themelia-tokenization: themes/portals;
+themelia-composition: owners/hierarchy; themelia-design: briefs/specs/critique.
+Whole view or redesign: agents/themelia-ui-designer.md in docs/consumer-skill.
+Before JSX write the coverage plan: one owner per region, or CUSTOM + parts.
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs <one domain noun>
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --roles
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs <symbol> --import <exact import>
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-tokens.mjs <role or root>
-Page owns h1/gutters; commands use one header.primaryAction and ordered
-header.secondaryActions. Confirm destructive commands with ConfirmDialog.
-Back links/tabs are optional. Base/layout + token-backed JSX can shape domains.
-Stack/Grid own gaps; Heading/Text own copy; Money/Date/Number format values.
-Semantic colors; neutral badges unless status is meaningful.
-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/re-run up to three rounds); app typecheck/lint/tests pass.
-Inspect narrow/wide light/dark hierarchy/insets; execute open/focus/error interactions.
-Report source, appearance and behavior separately; missing proof is unverified.
-Give kept warnings with file:line and reason.
+No raw panels, tables, pills, headings, modals or number/date formatting:
+Card, DataTable, Badge, Heading/Text, features/overlays, primitives.
+Page owns h1/gutters; route commands use header.primaryAction/secondaryActions.
+Card owns insets/footers; Stack/Grid own gaps. Never restyle an owner.
+Custom markup: semantic JSX + gap-space-*, p-surface, rounded-radius, semantic
+colors. Neutral badges except real status. Confirm destructive commands.
+Done: node node_modules/themelia-react-ui/docs/consumer-skill/scripts/check-composition.mjs <changed files>
+Fix checker errors (up to three rounds); run app type/lint/tests.
+Inspect narrow/wide light/dark and opened states; execute focus/error/callbacks.
+Source/appearance/behavior proof separately; missing proof stays unverified.
 <!-- themelia-react-ui:end -->
 ```
 

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

@@ -9,14 +9,28 @@ application data and never fetch or define a business metric.
 
 | 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. |
+| One KPI with value, trend or sparkline | `Metric` from `themelia-react-ui/blocks/analytics/charts` | `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/charts` | 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/charts` | 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/base/metadata-list` | Card-free; value primitives own formatting. |
-| Caller-owned chart series | `ChartCard` from `themelia-react-ui/blocks/analytics` with Recharts children | Card-free chart composition; `surface="card"` frames it. It wraps the children in `ChartContainer` with your `config`. |
+| Caller-owned chart series | `ChartCard` from `themelia-react-ui/blocks/analytics/charts` with Recharts children | Card-free chart composition; `surface="card"` frames it. It wraps the children in `ChartContainer` with your `config`. |
+
+The analytics family has three exact imports. Pick the entry by what it loads:
+
+- `themelia-react-ui/blocks/analytics/charts` holds every block that draws
+  with Recharts: `Metric`, `MetricGrid`, `MetricBar`, `MetricMicroGrid`,
+  `MetricGradient`, `MetricSparkline` and `ChartCard`. It needs the optional
+  `recharts` peer installed, even when a metric shows no sparkline.
+- `themelia-react-ui/blocks/analytics` is peer-free: `MetricComparison`,
+  `ActivityHeatmap`, `TimeDistributionRuler`, `MetricTrendChip`,
+  `MetricSkeleton` and the shared metric types, strings and formatters.
+- `themelia-react-ui/blocks/analytics/usage-card` is peer-free: `UsageCard`.
+
+`MetricData` and the other shared metric types can be imported from either of
+the first two entries.
 
 Start with these subject owners before constructing a Card with a number and
 supporting text. Reuse their formatting, hierarchy and relevant states when
@@ -44,6 +58,13 @@ 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.
 
+Use `tone` for a bordered metric's surface or a colored metric's progress
+indicator. MetricGrid forwards the tone to its cells. The `colorScheme` prop
+was removed in 3.0; `tone` is the only form. Use
+`destructive` in place of `danger` and `neutral` for a plain bordered
+surface. Colored metrics still default to primary progress. Set
+`tone="neutral"` for neutral progress.
+
 `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
@@ -67,6 +88,14 @@ chart follows the active theme. Use `ChartTooltip` with `ChartTooltipContent`
 rather than a custom tooltip; its `valueFormatter` formats only the value (for
 example as currency) and keeps the indicator and series label.
 
+ChartCard already supplies ChartContainer; do not nest a second one. For
+multiple series, put `ChartLegend content={<ChartLegendContent />}` inside the
+Recharts chart, or supply accessible direct series labels. Use config keys for
+series colors so the legend and marks agree in both themes. Footer copy can
+state a source or qualification; prose color explanations are a fragile legend.
+Substantial tables and disclosures belong in a body or peer region below the
+chart, with their own appropriate surface/inset owner.
+
 `MetricComparison` colours its delta by direction unless `current.trend` says
 whether the movement is good: pass `trend: 'positive'` when a fall in overdue
 balances or churn is the good outcome. Size the chart through the container, not fixed

package/docs/consumer-skill/references/building-views.md

@@ -0,0 +1,213 @@
+# Building views with Themelia
+
+Read this before writing any screen. It says what Themelia already gives you,
+the order to reach for it, and how to write the part it does not give you so
+that it still looks like Themelia.
+
+## What Themelia covers
+
+- **Simple views are 100% Themelia.** A list, a record page, a settings form, a
+  sign-in screen, a dashboard, a confirmation: every region has a public owner.
+  If you are writing a `<div>` with padding, a border or a text size on such a
+  view, you missed an owner.
+- **Domain views are about 70% Themelia.** The shell, page, header, cards,
+  tables, forms, facts, values, status, menus and overlays are owners. The
+  remaining 30% is the subject only your product has (an allocation board, a
+  reconciliation, a seat map). You write that part yourself, from Themelia's
+  parts and tokens, as described under [the custom part](#the-custom-part).
+- **Almost anything can be built this way.** A missing ready-made block is not
+  a reason to leave the system; it is the 30%.
+
+The [catalogue](catalogue.md) lists every family and component with one line
+on when to choose it. Read the sections for the layers you need before you
+search; it is the fastest way to learn what exists.
+
+## Reach in this order
+
+For each region of the view, take the first rung that fits:
+
+1. **A complete feature.** A workflow with its own state and states: tables,
+   filters, calendars, kanban, comments, media, search, editors, overlays.
+2. **A domain block.** A recognisable subject: an order summary, an invoice, a
+   timeline, a metric strip, a task card, a usage quota, an API token list.
+3. **Layout and base owners composed together.** `Page`, `Card`, `Stack`/`Grid`,
+   `MetadataList`, `Item`, `Badge`, `Alert`, form fields, value primitives.
+4. **An app-owned subject** built from rung 3 parts plus semantic JSX and
+   token-backed Tailwind. This is the custom part.
+
+A lower rung is allowed only after you looked at the rung above and can say
+what it lacks. "I did not find it" is not a reason: read the catalogue section
+and run the finder with the domain noun (`invoice`, `shipment`, `quota`), not
+only the control noun (`card`, `list`). Search one noun or one short phrase
+per call: every word must match, so a list of nouns returns nothing.
+
+Your domain will often have no block of its own name (a purchase order, a
+team member). Use the block for the same shape of data (`OrderSummary` for
+any totals, `OrderTimeline` for any history, `DataView` for any directory)
+and compose the rest from base owners.
+
+## Need → reach for
+
+| The view needs | Reach for | Import (after `themelia-react-ui/`) |
+| --- | --- | --- |
+| App chrome: sidebar, top bar, user menu | `AppLayout`, `AppSidebar`, `Header` | `layout/app-shell`, `layout/sidebar`, `layout/header` |
+| A route: title, commands, tabs, loading/error/empty | `Page` | `layout/page` |
+| Main column plus context column | `Page` `aside`, or `TwoColumnLayout` | `layout/page`, `layout/containers` |
+| Settings with section navigation | `AsideNavShell` + `FormSection` | `layout/settings`, `base/forms` |
+| Sign in, sign up, reset | `AuthShell` and its parts | `layout/auth` |
+| Marketing or content page | `Container`, `Section` | `layout/containers` |
+| A filterable, sortable record list | `DataView`, or `FilterProvider` → `DataTable` | `features/data-view`, `features/filters`, `features/table` |
+| A small static table | `Table` | `base/table` |
+| A framed subject with title and actions | `Card` | `base/cards` |
+| Label/value facts | `MetadataList` | `base/metadata-list` |
+| A list of rows with media, title, actions | `ItemGroup` + `Item` | `base/item` |
+| Money, dates, numbers, names, contacts, empty values | `Money`, `Date`, `RelativeTime`, `Number`, `Percent`, `Name`, `Email`, `Phone`, `EmptyValue`, `MonoValue` | `primitives` |
+| Headings and copy | `Heading`, `Text`, `Label`, `TextLink` | `typography` |
+| Status, counts, kinds | `Badge` | `base/badge` |
+| Notices | `Alert` | `base/feedback` |
+| Nothing here yet / failed / loading | `EmptyState`, `ErrorState`, `LoadingState`, `Skeleton` | `blocks/data-display`, `base/feedback`, `base/skeleton` |
+| KPIs and charts | `MetricGrid`, `MetricBar`, `Metric`, `ChartCard` | `blocks/analytics/charts` |
+| One inline figure | `InlineStat` | `blocks/data-display` |
+| Quotas and usage | `UsageCard` | `blocks/analytics/usage-card` |
+| History, steps, milestones | `Timeline`, `StepsCard`, `MilestonesTimeline`, `ActivityLog` | `blocks/timelines`, `features/activities` |
+| Orders, invoices, carts, shipments, payments, addresses | `OrderSummary`, `InvoiceLineItems`, `CartSummaryCard`, `ShipmentTracking`, `PaymentMethod`, `AddressCard`, `Receipt` | `blocks/commerce` |
+| Products, options, variants | `ProductOverview`, `ProductVariantsManager` | `features/products` |
+| Tasks and boards | `TaskCard`, `Kanban` | `blocks/planning`, `features/kanban` |
+| Schedules | `EventCalendar`, `AppointmentCalendar` | `features/event-calendar`, `features/appointment-calendar` |
+| Discussion | `Comments`, `Message` | `features/comments`, `blocks/collaboration` |
+| Files and media | `FileUpload`, `Dropzone`, `UploadTray`, `Attachment`, `MediaGallery`, `MediaLibrary` | `base/upload`, `base/upload-queue`, `base/attachment`, `base/media-gallery`, `features/media-library` |
+| A form | `ControlledFormField`, `FormSection`, `FormActionsBar`; `SchemaForm` for schema-driven | `base/forms`, `features/schema-form` |
+| Pick one or many from a searchable list | `Combobox`, `Select`, `PopoverMenu` | `features/combobox`, `base/choice-inputs`, `base/popover-menu` |
+| Edit one value in place | `InlineEdit` | `base/inline-edit` |
+| Row or record commands | `ActionMenu`, `ActionButtons`, `BatchActionBar` | `base/action-menu`, `base/batch-action-bar` |
+| Expand and collapse | `Accordion`, `Collapsible` | `base/accordion`, `base/display` |
+| Sections of one record | `Tabs`, `NavigationTabs` | `base/navigation` |
+| A modal, drawer or confirmation | `ActionDialog`, `ActionDrawer`, `ConfirmDialog` | `features/overlays` |
+| Transient feedback | `Toaster`, `toast` | `base/toaster` |
+| Rich text | `RichText` to show, `RichTextEditor` to edit | `typography/rich-text`, `features/rich-text-editor` |
+| Search everything | `GlobalSearch` | `features/global-search` |
+| Maps and places | `Map`, `PlaceAutocomplete` | `features/map` |
+| AI conversation and its parts | `AiChat`; `Ai*` blocks | `features/ai-chat`, `blocks/ai` |
+| API keys, secrets, dangerous actions | `ApiTokenManager`, `CopyableSecretAlert`, `SensitiveActionCard` | `blocks/admin` |
+| Codes, copy, QR | `CodeBlock`, `Copyable`, `QRCode` | `base/code-block`, `base/copyable`, `base/qr-code` |
+
+The table is a map, not the API. The installed declarations are the API: read
+`dist/components/<family>/*.d.ts` for the import you chose (the finder prints
+the path as `nextReads.declaration`). Never read or import the package's
+`src/`. The inspector answers one question at a time; add `--prop <name>`:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs <domain noun>
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs <Symbol> --import <exact import>
+```
+
+## Cases the map does not settle
+
+- **A table in a card.** `DataTable` and `DataView` draw their own surface:
+  place them directly in the page. A small `Table` under a card title goes in
+  `Card contentPadding="none"`, which keeps the header inset and lets the
+  table own its edges.
+- **Table cells.** `features/table` exports the cell owners: `AvatarCell`
+  (name with avatar), `ResourceCell`, `StatusCell`, `DateCell`, `CellStack`
+  and `CellValue`. Numeric columns align with `text-end` on `TableHead` and
+  `TableCell`; alignment is geometry, not restyling.
+- **No rows.** A table or data view states its own empty result through
+  `strings.emptyState` and `emptyStateAction`. `EmptyState` is for a region
+  that has no owner of its own.
+- **Blocks that take strings.** `OrderSummary`, `SummaryPanel` and timeline
+  entries take already-formatted text. Format money with `useMoneyFormatter`
+  from `primitives` and dates with the app's own formatter, once, in the data
+  mapping; never write a currency symbol or date string by hand in JSX.
+- **A person.** A person in a row is `AvatarCell` or `Item` with `Avatar`; a
+  person as the page subject is the `Page` header with `Avatar` in
+  `slots.beforeTitle` and status in `slots.titleSuffix`.
+- **Read-only on/off facts.** `BooleanIndicator` inside `MetadataList`, or
+  `RolePermission` for grouped permissions.
+- **Whole quantities.** `DecimalInput` with `decimalPlaces={0}`.
+- **Feedback after a command.** `toast` when the app mounts `Toaster` (it
+  needs the `sonner` peer); otherwise an `Alert` above the affected region.
+- **Short forms.** Two or three fields in an `ActionDialog` can use `formId`
+  with a native `<form>` and `FormField`; longer or validated forms use the
+  typed bindings in [typed workflows](rhf-workflows.md).
+
+## Write the coverage plan first
+
+Before JSX, list the regions of the view and name an owner for each. Keep it
+in your notes or the view spec; it takes a minute.
+
+```text
+Order detail
+  shell            AppLayout                      layout/app-shell
+  route            Page (aside)                   layout/page
+  status, facts    Badge in titleSuffix, MetadataList
+  lines            OrderLineItem in Card          blocks/commerce
+  totals           OrderSummary                   blocks/commerce
+  customer         OrderCustomer                  blocks/commerce
+  payments         OrderTransactions              blocks/commerce
+  history          OrderTimeline                  blocks/commerce
+  refund           ActionDrawer + ControlledFormField
+  pick-and-pack    CUSTOM: allocation by warehouse (Card, Stack, Item, Number, Badge)
+```
+
+Every row has an owner or says `CUSTOM` with the parts it will be made from.
+A view with more `CUSTOM` rows than owner rows needs another look at the
+catalogue. A simple view has no `CUSTOM` row.
+
+## You wrote this → use this
+
+| Hand-written | Use |
+| --- | --- |
+| `<div className="rounded border p-4">` as a panel | `Card` |
+| `<h1>`–`<h4>`, `<p>` with size and weight classes | `Heading`, `Text` with `size`/`weight` props |
+| `flex flex-col gap-4`, `grid grid-cols-3 gap-6` for ordinary siblings | `Stack`, `Grid`, `AdaptiveGrid` with a semantic `gap` |
+| `<table>` with your own header, sorting or paging | `DataTable` or `DataView` |
+| `<dl>` or two-column label/value rows | `MetadataList` |
+| A coloured `<span>` pill | `Badge` |
+| `toLocaleString`, `Intl.NumberFormat`, a date library in JSX | `Money`, `Number`, `Percent`, `Date`, `RelativeTime` |
+| `—` or `N/A` for a missing value | `EmptyValue` |
+| A page title row with buttons | `Page` `header` with `primaryAction`/`secondaryActions` |
+| `fixed inset-0` or a modal library | `ActionDialog`, `ActionDrawer`, `ConfirmDialog` |
+| A centred icon and "No results" text | `EmptyState` |
+| A spinner in an empty box | The owner's loading state, or `Skeleton` |
+| A `…` button with a dropdown | `ActionMenu` |
+| `text-gray-500`, `bg-blue-50`, hex colours | Semantic roles: `text-muted-foreground`, `bg-muted`, status tones on `Badge`/`Alert` |
+| `p-4`, `gap-3`, `rounded-lg`, `text-[13px]` on your own markup | `p-surface`, `gap-space-*`, `rounded-radius`, a `Text` size |
+
+## The custom part
+
+The part Themelia does not ship is written with the same rules its own blocks
+follow, so it cannot be told apart from them.
+
+- **Start from an owner's seam.** Most "custom" needs are an existing block
+  plus one region: use its slots, `render` props and compound parts first.
+- **Compose, do not draw.** The subject is `Stack`/`Grid` for structure,
+  `Heading`/`Text` for copy, value primitives for data, `Badge` for status,
+  `Item` for rows, `Button`/`ActionMenu` for commands. Your own elements carry
+  semantics (`<section>`, `<ul>`, `<dl>`) and layout, not looks.
+- **Tailwind is for geometry.** Tracks, container queries, alignment, overflow
+  and positioning on your own elements. Spacing, radius, colour and type come
+  from the shared roles: `gap-space-*`, `p-surface`, `px-row-x`,
+  `rounded-radius`, semantic colours. See
+  [domain structures](domain-structures.md#choose-classes-by-responsibility).
+- **Card at the boundary.** Write the subject card-free and wrap it in `Card`
+  where it is placed. No box inside a box.
+- **Never restyle an owner.** No padding, colour, radius or font classes on a
+  Themelia component or its `*ClassName` slots. If an owner looks wrong, the
+  props or the composition are wrong.
+- **Give it the states an owner would have.** Loading, empty, error, disabled
+  and narrow width, using the same owners (`Skeleton`, `EmptyState`, `Alert`).
+
+Use the shipped sources as models. The [templates](../../../templates/README.md)
+are whole screens, and the [recipes](../examples/manifest.json) are focused
+compositions; `custom-composition.tsx`, `token-domain-structure.tsx` and
+`commerce-lines.tsx` show an app-owned subject beside package blocks.
+[App-owned composites](custom-composition.md) covers choosing the seam in
+depth, and [view craft](view-craft.md) covers what makes the result read well.
+
+## Done for coverage
+
+- Every region in the plan uses its named owner; every `CUSTOM` row is built
+  only from Themelia parts and shared roles.
+- No row in "You wrote this" appears in the diff.
+- `check-composition.mjs` passes on the changed files, and the view has been
+  looked at narrow and wide, light and dark ([review](review.md#done-means)).