themelia-ui 3.1.0 → 3.2.0

package/.agents/skills/themelia-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: themelia-ui
-description: Use when a React consumer is selecting, importing, composing, theming, localizing, integrating or upgrading themelia-ui components — forms, routing, data, SSR, CSP, consumer CSS overrides, Tailwind, and migrating between versions with the packaged codemod. Do not use for maintaining package internals.
+description: Use when a React consumer is selecting, importing, composing, theming, localizing, integrating or upgrading themelia-ui components — structural layouts, blocks, spacing, responsive grids, forms, routing, data, SSR, CSP, consumer CSS overrides, Tailwind, and migrating between versions with the packaged codemod. Do not use for maintaining package internals.
 ---
 
 <!-- GENERATED by themelia-ui/scripts/gen-agent-skill.mjs -->
@@ -13,8 +13,14 @@ uses CSS Modules over Base UI, publishes exact module subpaths, and has no `ui/`
 
 ## Workflow
 
-1. Search the packaged catalogue by the job the interface must do.
-2. Read the best match's `chooseWhen`, `avoidWhen`, alternatives, status, and optional peers.
+1. Read the application's instructions and policy skills; they own domain decisions. Identify
+   the installed package version and check this copy with the packaged installer `--check`.
+   Review drift before reinstalling; keep application policy in a separate skill.
+2. Map owners: route, surface, section, fact, metric, editable group, field, transport and command.
+   Read `references/composition.md` for their insets, names and parent responsibilities. Search
+   the catalogue by job and context; read `chooseWhen`, `avoidWhen`, alternatives and peers.
+   For page geometry, gaps and responsive widths, read `references/structure-and-spacing.md`;
+   for analytics, onboarding, timelines and admin presentation, read `references/blocks.md`.
 3. Open that module's generated API reference before writing JSX. It contains every public
    declaration, inherited prop contract, dependency, and attributed live-preview recipe.
 4. Prefer the highest ready module that owns the behavior, then customize it at the lowest
@@ -24,6 +30,16 @@ uses CSS Modules over Base UI, publishes exact module subpaths, and has no `ui/`
 6. Keep application policy in the application, then verify the composed result in its real
    route, theme, density, data states, keyboard flow, and production bundle.
 
+For a shared component/style change, trace its callers first. Select representatives of each
+affected surface and check the initiating control, parent width, inset and portal owners.
+Use `references/reference-workflows.md` when several modules meet; copy the complete source
+directory including helpers. Run the packaged read-only diagnostics against explicit source
+paths and treat advisory findings as review prompts. Read only the relevant guide.
+If the catalogue or declaration is absent, name the missing path and use the installed package's
+export map/types or request the missing artifact. Do not infer an API from another version.
+If browser access is unavailable, finish independent type/build work and report browser
+behavior and appearance as unverified.
+
 **Upgrading between versions** comes before any of that. Read the version's section in
 `references/migration.md`, then run the packaged codemod — dry first — and handle what it
 reports (removed tokens, overrides that now set a shared name, look-alike Tailwind utilities)
@@ -33,6 +49,7 @@ by hand. Re-run the skill installer afterwards so this skill matches the install
 node node_modules/themelia-ui/scripts/consumer/codemod.mjs --dry-run src/
 node node_modules/themelia-ui/scripts/consumer/codemod.mjs src/
 node node_modules/themelia-ui/scripts/consumer/install-skill.mjs --project=.
+node node_modules/themelia-ui/scripts/consumer/install-skill.mjs --project=. --check --json
 ```
 
 ## Installed-package authorities
@@ -65,7 +82,7 @@ node node_modules/themelia-ui/scripts/consumer/find-component.mjs --peer=@tansta
 node node_modules/themelia-ui/scripts/consumer/find-component.mjs --help
 ```
 
-It indexes 97 modules, 395 attributed live recipes, and
+It indexes 97 modules, 404 attributed live recipes, and
 119 live preview routes by public symbol, module id, recipe title, preview route,
 component capabilities, descriptions, and positive selection guidance. Negative `avoidWhen` guidance is never treated as a
 recommendation. `--json` includes the exact
@@ -132,7 +149,10 @@ analytics, persistence, translation orchestration, and domain decisions. Pass th
 documented props, callbacks, accessors, slots, render props, hooks, and provider seams.
 
 Read `references/composition.md` for page examples and
-`references/composition-ladder.md` for tier-by-tier tradeoffs.
+`references/composition-ladder.md` for available extension seams. Structural helpers arrange
+siblings; subject blocks own a recognizable presentation. Stack has gap and alignment props,
+no padding prop. Page already supplies a Container, and DataView already supplies its frame.
+Check child insets before adding parent gaps; flat FormSections retain their inset.
 
 ## Imports and CSS delivery
 
@@ -224,10 +244,11 @@ export function ScopedPreview() {
 
 Theme through the public contract in `node_modules/themelia-ui/src/styles/TOKENS.md`: about
 eighty variables, declared once at `:root`, each colour a `light-dark(light, dark)` pair. Set
-the ones you change on `:root` (or on any element, for a region); nothing below `:root`
-declares them again. A denser region is the provider's `density` or `scale`, and type alone
-is `typography.scale`. A component's own variables are private (`--_x`), never an override
-surface.
+the ones you change on `:root` (or on any element, for a region). Component defaults inherit
+them; explicit scope overrides and density presets establish new values on their regions.
+`density` changes spacing and control heights; `scale` also changes icons and type;
+`typography.scale` changes type alone. A component's own variables are private (`--_x`), never
+an override surface.
 
 Kit component rules are layered, so ordinary unlayered consumer CSS wins whatever its order,
 without `!important`. Target stable documented `data-slot` or
@@ -265,6 +286,9 @@ portals, strict CSP, or streaming SSR. Read `references/theming.md` before defin
 | `references/theming.md` | changing color, radius, density, scale, typography, DTCG, or Tailwind integration |
 | `references/provider-and-scoping.md` | configuring roots, nested regions, portals, CSP, or SSR |
 | `references/composition.md` | building application-specific pages and business components |
+| `references/structure-and-spacing.md` | choosing structural blocks, insets/gaps, widths, responsive grids, scroll owners or bleed |
+| `references/blocks.md` | choosing analytics, onboarding, timelines or admin blocks and their application seams |
+| `references/reference-workflows.md` | complete compositions, state ownership and helper sources |
 | `references/composition-ladder.md` | choosing the highest ready tier and lowest extension seam |
 | `references/framework-wiring.md` | connecting router, data, permissions, persistence, and rendering boundaries |
 | `references/forms.md` | binding fields to React state, react-hook-form, or another controller |
@@ -276,6 +300,11 @@ portals, strict CSP, or streaming SSR. Read `references/theming.md` before defin
 
 ## Consumer completion checklist
 
+Record the package/skill versions, selected owners and public seams, changed callers, tested
+routes and states, widths/themes/densities/locales, keyboard/focus interactions, exact commands
+and observed results. List unavailable checks and application acceptance still required.
+Only claim checks you executed; a successful typecheck cannot establish visual or workflow success.
+
 - Exact module import and its CSS resolve from the installed package.
 - Only the selected modules' optional peers are installed and bundled.
 - Public props and slots are used; no internal path, hash class, or undocumented token leaks in.

package/.agents/skills/themelia-ui/manifest.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "packageVersion": "3.2.0",
+  "files": {
+    "SKILL.md": "c9a3884bc4315abd7425417e64aa68460a3a890c3f93f8f201d6dd0e3f79209d",
+    "references/api-compatibility.md": "7ecd0b9be0eff433391709fdf08321885d9ac4f1f30d99579b9ec179ea070da2",
+    "references/blocks.md": "42772d3390cdb22d0aac25dd47ddc0ed7de18159a760b3f8dc09eb9346b386c3",
+    "references/composition-ladder.md": "f02ee3b3f55464684ba993d7e129915d5c4732b329d8b9f702ab7579ef6322f2",
+    "references/composition.md": "ccf8fa769cc605c9f7d59ec939e3be5873f97b5d4158eee5eb04dc62d523f270",
+    "references/forms.md": "8e1b86b5da221f04855b59f1ebcf90c7cc6fe63284be34b30afd09e4d978fafb",
+    "references/framework-wiring.md": "c98ca307c33c0e89ba4371d3d893af2aa0fd219aeea7413d534c3ac83d4cbf20",
+    "references/i18n.md": "74759967f8460ceb2e41c18d6ff20c62f40ccd745bbc87b645106360be3d7c59",
+    "references/imports.md": "c45ff607b729b9b00b8a58ed62bf0da9f12c355a554f3ef7b0aa5f17d9b7b684",
+    "references/installation.md": "60e3ca9ac46f5d43f27cb3eacf482bb4bbae05f5bc673f10a3fe7aa6fd34b5ed",
+    "references/migration.md": "e8e3875e4db01b6ed32246733e493f8077db8dd1b18ca82a8309af0889e74381",
+    "references/provider-and-scoping.md": "71a9844192804c3be7c604545b9592bf17e6f591595553d6a91b1de9b954259a",
+    "references/reference-workflows.md": "9f7a02aa3d34934cd8a22fbabcc377a880513c251bba0b2a49f5ecdc50f7c47c",
+    "references/structure-and-spacing.md": "e44c3f90e2d3c4aa590c7a88115e7806d6e0fdff1c7bba9ce862894fdd671653",
+    "references/theming.md": "f5e14f5c72274a7b58a1148a8365334aafdbb884bac2ed6854022a895e3c9023",
+    "references/troubleshooting.md": "f81f8fb782933bedadf347efbc15898bd531b0719d9ffe6f1ff2cc6d309837d8",
+    "references/verification.md": "c8a8f2313021d7f15fe02a6f49f46b5bf457ffba69ece9f962c836bd1a1a3a3e"
+  }
+}

package/.agents/skills/themelia-ui/references/api-compatibility.md

@@ -1,6 +1,6 @@
 # API compatibility
 
-Within a major version, exact package subpaths, exported names, callable signatures, and
+Exact package subpaths, exported names, callable signatures, and
 exported props/type members are compatibility surfaces. Public global theme tokens, documented
 `data-slot` and BEM hooks, and the `strings` contracts are also consumer contracts.
 
@@ -15,7 +15,8 @@ exported props/type members are compatibility surfaces. Public global theme toke
 | a documented default changes | behavioural change; release notes required |
 | component token or hashed CSS Module name changes | internal unless documented as an extension point |
 
-3.1 removes obsolete aliases and adapters. Removed names do not stay available solely for an
+3.1 includes breaking changes despite its minor version number: it removes obsolete aliases
+and adapters. Removed names do not stay available solely for an
 upgrade window. A breaking release records the replacement in the migration reference and
 the changelog; consumers pin the old version until they are ready to update.
 

package/.agents/skills/themelia-ui/references/blocks.md

@@ -0,0 +1,123 @@
+# Choosing and composing blocks
+
+A structural block arranges regions; a subject block renders a recognizable job such as
+metrics, onboarding or an order summary. Use [Structure and spacing](structure-and-spacing.md)
+for page geometry, surfaces and gaps. Start with a ready subject block when its vocabulary
+fits the product, then use its documented props, callbacks or parts. The application keeps
+data, permission checks, routing, mutation and persistence.
+
+## Published subject modules
+
+| Job | Exact subpath and examples | Application owns | Optional peers |
+| --- | --- | --- | --- |
+| Quantities, changes and plots | `themelia-ui/blocks/analytics`: MetricGrid, Metric, MetricComparison, ChartCard, ActivityHeatmap | Measures, period, comparison meaning, loading/errors and metric actions | `recharts`, for the module even when the adopted block has no plot |
+| Setup tasks completed over time | `themelia-ui/blocks/onboarding`: Checklist | Step status, content, submission and persistence | None |
+| Milestones, changelog or linear progress | `themelia-ui/blocks/timelines`: MilestonesTimeline, ChangelogTimeline, Steps, StepsBar | Sequence, status, dates and navigation | None |
+| Permissions and credential management | `themelia-ui/blocks/admin/access`: RolePermissions, CredentialList, SensitiveAction | Authorization, actual secrets, deletion confirmation and mutations | None |
+| Orders, invoices, inventory and payment summaries | `themelia-ui/blocks/admin/commerce`: OrderSummary, InvoiceLineItems, InventorySection, PaymentTimeline | Commerce records, calculation policy, commands and transport | None |
+
+These are modules, not broad barrels: there is no `themelia-ui/blocks` import. General and
+admin profiles come from the same installation. Admin is presentation vocabulary rather
+than an authorization layer; importing an admin block does not protect its actions or data.
+The generated [import table](imports.md) is authoritative for optional peers.
+Do not assume a symbol is peer-free because its own UI looks simple.
+
+Open the selected API before JSX: analytics (`node_modules/themelia-ui/docs/generated/components/blocks--analytics.md`),
+onboarding (`node_modules/themelia-ui/docs/generated/components/blocks--onboarding.md`),
+timelines (`node_modules/themelia-ui/docs/generated/components/blocks--timelines.md`),
+admin access (`node_modules/themelia-ui/docs/generated/components/blocks--admin--access.md`), or
+admin commerce (`node_modules/themelia-ui/docs/generated/components/blocks--admin--commerce.md`).
+They list exact record shapes, defaults, strings, dependencies and preview recipes.
+
+## Facts versus quantities
+
+MetadataList owns label/value facts such as owner, status, address or a date. A numeric
+identifier is still a fact. MetricGrid/Metric own measures such as delivered messages,
+revenue or a conversion rate, with optional comparison and trend. Put prose facts beside
+quantities rather than turning every value into a metric tile.
+
+```tsx compile
+import { ContentBlock, MetadataList } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { MetricGrid, type MetricData } from "themelia-ui/blocks/analytics"
+import { Page } from "themelia-ui/layout/page"
+
+const metrics: MetricData[] = [
+  { id: "delivered", label: "Delivered", value: 248 },
+  { id: "opened", label: "Opened", value: null, subtitle: "Tracking unavailable" },
+]
+
+export function DeliveryOverview() {
+  return <Page header={{ title: "Delivery overview", description: "Current campaign" }}>
+    <Stack>
+      <MetricGrid metrics={metrics} variant="card" />
+      <ContentBlock title="Campaign details">
+        <MetadataList items={[
+          { id: "owner", label: "Owner", value: "Alex" },
+          { id: "status", label: "Status", value: "Sending" },
+        ]} />
+      </ContentBlock>
+    </Stack>
+  </Page>
+}
+```
+
+Use `null` for an unavailable MetricData value; zero means a measured zero. MetricGrid's
+loading contract is for initial loading. For error or refresh behavior, inspect the adopted
+component's exact API rather than assuming every analytics block accepts the same props.
+The [communications workflow](reference-workflows.md) demonstrates retained figures,
+failure feedback, retry, unknown tracking and a separate facts region.
+
+## Compose without duplicating owners
+
+Inspect whether a block already owns its title, surface, controls and responsive layout
+before surrounding it with another Card or Grid. MetricGrid already arranges tiles;
+ChartCard already owns its chart frame; FormSection already owns an editable section's
+header and inset. Use a sibling surface for an independent subject and ContentBlock for
+supporting prose inside one. [Composition](composition.md#decide-the-owners-before-jsx)
+describes the owners in detail.
+
+Keep default typography and spacing with those owners. Do not invent `size`, `padding`,
+`error` or `strings` props by analogy with another block. Use a documented slot or render
+prop for one region; use public parts or an application composition when the arrangement
+must differ. No block needs every extension seam. The [composition ladder](composition-ladder.md)
+is a discovery aid; the selected API remains the contract.
+
+## Compose your own subject
+
+When the ready block's vocabulary cannot express the product, start from its public
+lower-tier recipe rather than copying internals. The live block pages include these
+compose-your-own examples; their source is also embedded in
+recipes.json (`node_modules/themelia-ui/docs/generated/recipes.json`) under the exact id below and in the
+recipe book (`node_modules/themelia-ui/docs/build/recipes.md`). The recipe imports identify the adopted modules and
+their peer requirements; they do not require importing the corresponding ready block.
+
+| Subject | Recipe id | Public building blocks |
+| --- | --- | --- |
+| A custom measure | `analytics-blueprint` | Card, Stack, Money, Badge, Sparkline |
+| Setup checklist | `blocks-checklist-blueprint` | Progress, Accordion, IconBadge, Text, Button |
+| Release timeline | `blocks-changelog-blueprint` | Timeline, MonoValue, Badge |
+| Role/permission summary | `blocks-roles-blueprint` | Table, Badge, VisuallyHidden |
+| Custom order summary | `cart-summary-blueprint` | Card, MetadataList, Money, Button, toast |
+
+For example, retrieve the exact checklist source from the installed package:
+
+```bash
+node <<'NODE'
+const fs = require('node:fs')
+const { recipes } = JSON.parse(fs.readFileSync('node_modules/themelia-ui/docs/generated/recipes.json', 'utf8'))
+const recipe = recipes.find(item => item.id === 'blocks-checklist-blueprint')
+if (!recipe) throw new Error('Recipe missing from this installed version')
+process.stdout.write(recipe.code)
+NODE
+```
+
+These examples establish presentation seams, with fixed sample data and mock callbacks.
+Keep the application's real permission model, calculations and completion state in its
+own component. Use the [complete workflows](reference-workflows.md) when the task needs
+submission, lookup, selection or retained-draft behavior beyond a presentation recipe.
+
+For translated copy, use the selected module's typed strings and exported defaults. Product
+labels and record content remain application copy. Test permissions, loading/empty/error
+states, long labels, keyboard interaction, RTL and the adopted density in the real route;
+the package's previews do not establish application acceptance.

package/.agents/skills/themelia-ui/references/composition-ladder.md

@@ -10,9 +10,9 @@ The rungs are ordinary props; controlled state and callbacks when state exists;
 named slots; render props; exported parts; headless hooks; and complete recipes. Passive
 modules may stop at the first rung. Interaction features normally expose several.
 
-This table is derived from what each module declares, so it cannot describe a seam that
-was removed or miss one that was added. The table focuses on feature modules, where the
-higher rungs are meaningful; the columns start at accessors.
+This table summarizes detected declarations and recipes. It is a discovery aid, not a
+prop contract: open the selected module API for exact signatures and supported seams.
+It focuses on feature modules; the columns start at accessors.
 
 | module | accessors | slots | render props | headless hook | partials | recipe |
 | --- | :-: | :-: | :-: | :-: | :-: | :-: |
@@ -41,7 +41,7 @@ higher rungs are meaningful; the columns start at accessors.
 | `features/table` | ● | ● | · | ● | ● | ● |
 | `features/theme-tweaker` | · | ● | · | ● | ● | ● |
 
-## The four the plan names
+## Four feature examples
 
 Global Search, Filters, Comments and Data View are the demonstration cases, because a
 ladder that only works on a Badge proves nothing. Each is usable at three heights:
@@ -50,7 +50,7 @@ ladder that only works on a Badge proves nothing. Each is usable at three height
 
 **Ready-made** — `GlobalSearch`, dropped in with props and callbacks.
 
-**Region-customized** — 8 exported parts, so a region can be replaced without copying the whole: `GlobalSearchDialog`, `GlobalSearchEmptyState`, `GlobalSearchFooter`, `GlobalSearchIdleState`, `GlobalSearchInput`, and 2 more.
+**Region-customized** — 7 other public exports to inspect for region customization: `GlobalSearchDialog`, `GlobalSearchEmptyState`, `GlobalSearchFooter`, `GlobalSearchIdleState`, `GlobalSearchInput`, and 2 more.
 
 **Headless** — `useGlobalSearch`, for presentation the parts cannot express.
 
@@ -58,7 +58,7 @@ ladder that only works on a Badge proves nothing. Each is usable at three height
 
 **Ready-made** — `FilterLayout`, dropped in with props and callbacks.
 
-**Region-customized** — 18 exported parts, so a region can be replaced without copying the whole: `AsyncFilterEditor`, `DateFilterEditor`, `FilterEditor`, `FilterErrorBoundary`, `FilterOperator`, and 12 more.
+**Region-customized** — 17 other public exports to inspect for region customization: `AsyncFilterEditor`, `DateFilterEditor`, `FilterEditor`, `FilterErrorBoundary`, `FilterOperator`, and 12 more.
 
 **Headless** — `useAsyncOptions`, `useFilterCache`, `useFilterGroups`, `useFilters`, for presentation the parts cannot express.
 
@@ -66,7 +66,7 @@ ladder that only works on a Badge proves nothing. Each is usable at three height
 
 **Ready-made** — `Comments`, dropped in with props and callbacks.
 
-**Region-customized** — 6 exported parts, so a region can be replaced without copying the whole: `CommentAttachmentChip`, `CommentComposer`, `CommentContent`, `CommentItem`, `CommentTimeline`.
+**Region-customized** — 5 other public exports to inspect for region customization: `CommentAttachmentChip`, `CommentComposer`, `CommentContent`, `CommentItem`, `CommentTimeline`.
 
 **Headless** — `useAttachmentUpload`, `useComments`, for presentation the parts cannot express.
 
@@ -74,6 +74,6 @@ ladder that only works on a Badge proves nothing. Each is usable at three height
 
 **Ready-made** — `DataView`, dropped in with props and callbacks.
 
-**Region-customized** — 6 exported parts, so a region can be replaced without copying the whole: `DataViewPagination`, `DataViewShell`, `DataViewTableFrame`, `DataViewToolbar`, `SavedViewTabs`.
+**Region-customized** — 5 other public exports to inspect for region customization: `DataViewPagination`, `DataViewShell`, `DataViewTableFrame`, `DataViewToolbar`, `SavedViewTabs`.
 
 **Headless** — `useDataView`, for presentation the parts cannot express.

package/.agents/skills/themelia-ui/references/composition.md

@@ -20,6 +20,10 @@ ready-made surface does not express the job.
 compose both; neither may import a block. The complete generated graph is in
 Profiles (`node_modules/themelia-ui/docs/generated/profiles.md`).
 
+For structural blocks, spacing roles and responsive widths, use
+[Structure and spacing](structure-and-spacing.md). For ready analytics, onboarding,
+timeline and admin presentations, use [Choosing blocks](blocks.md).
+
 ## The composition ladder
 
 Use the lowest rung that solves the real requirement:
@@ -142,6 +146,13 @@ The invoice example above is the canonical shape: `Page` for route geometry,
 `MetadataList` and primitives for facts, then domain callbacks on package actions. Keep the
 record type out of the package.
 
+When the task also fits the standard loading, empty, error and retry presentation, use
+`ResourceShowShell` or `ResourceIndexShell` from `features/resource`. Those shells already
+own a header, body and state replacement; do not duplicate that route header by wrapping
+them in another Page. Page remains appropriate for a custom record arrangement where the
+application already owns lifecycle feedback. Read the
+resource API (`node_modules/themelia-ui/docs/generated/components/features--resource.md`) for state and slot contracts.
+
 ### Form
 
 ```tsx fragment — validation, field values, submit mutation, and product copy remain in the app
@@ -191,7 +202,7 @@ documentation tree whose vocabulary is not settings.
 
 Look up a specific task with the offline finder. Exact symbols take priority; `--explain`
 shows matched components, selection reasons and direct API anchors. `--json` exposes the
-same records for tools. Guidance marked `family` is a fallback, not a component-specific
+same records for tools. Guidance marked `module` is a fallback, not a component-specific
 recommendation. An empty result means refine the query or inspect the catalogue, not invent
 an export.
 
@@ -314,6 +325,92 @@ Only use states the selected module exposes; the API reference is authoritative.
 complete examples above type-check against the built package, but their application
 callbacks are illustrative: verify persistence and browser behaviour in your app.
 
+## Decide the owners before JSX
+
+| Owner | Insets and type | Name and command scope | Parent responsibility |
+| --- | --- | --- | --- |
+| `Page` | Route geometry; header owns heading type | One route heading; route commands | Data, routing and independent subjects |
+| `Card` / parts | Surface and content inset; header owns title/description | A bounded subject; commands for that subject | Arrange sibling subjects, choose heading level |
+| `ContentBlock` | Title/content gap; `plain` has no inset, decorated surfaces add one | Supporting content within a subject | Decide whether another independent surface is warranted |
+| `MetadataList` / values | Fact layout; labels and semantic value formatting | Read-only facts, not editable labels | Permission-filtered records and value descriptors |
+| Analytics blocks | Quantity hierarchy and responsive metric arrangement | Measures and their period; metric actions | Query, unknown quantities and interpretation |
+| `FormSection` | Section inset and heading; `flat` retains its padding | Editable region title; section-specific actions | Form, values, validation and completion |
+| `FieldGroup` | Related control arrangement and support line | Fieldset/legend for a group; children retain distinct labels | Group disabled state and validation policy |
+| `FormField` / binding | Label and support typography, control association | One editable field | Value, mutation and explicit name/ARIA overrides |
+| `Stack` / `Grid` | Shared gaps; no new typography owner | Passive arrangement | Choose whether child insets already supply separation |
+| `DataView` | Filter/table shell and responsive filter presentation | Resource-browser commands | Transport, page totals and selection lifetime |
+| `DataTable` | Tabular interaction and table geometry | Column/row names and row commands | Filters, surrounding surface and server transport |
+| `FilterLayout` / slots | Responsive controls and sheet | Filter controls only | Shared filter state; put export/create in action slots |
+
+`surface="flat"` changes decoration, not the inset contract. Several flat FormSections
+inside CardContent accumulate the card content inset and each section's inset. Use the
+ready Card body when that separation is useful; use parts when you need a different region
+arrangement. `Stack gap="none"` is appropriate when adjacent sections already own their
+vertical separation. Do not compensate by assigning private padding variables or local type.
+
+These are fragments; the [complete workflows](reference-workflows.md) include state,
+helpers and submission behavior.
+
+```tsx fragment — fields and subject data come from the application
+<Card title="Account details">
+  <Stack gap="none">
+    <FormSection surface="flat" title="Contact">{contactFields}</FormSection>
+    <FormSection surface="flat" title="Billing">{billingFields}</FormSection>
+  </Stack>
+</Card>
+```
+
+```tsx fragment — parts expose the same owners; table rows and columns are application data
+<Card>
+  <CardHeader title="Related records" titleLevel={2} />
+  <CardContent><DataTable data={rows} columns={columns} /></CardContent>
+</Card>
+```
+
+Use sibling Cards for independent subjects. Use ContentBlock inside a Card for supporting
+prose. Repeating the route heading as each Card title adds no new subject. Repeating a
+FormField label in a nested DisplayLabel creates competing names; supply the field label
+once and let FormField associate it. A FieldGroup legend names the group, so its children's
+labels should identify their distinct values. Labels on different records may repeat.
+
+```tsx fragment — each subject supplies its own application-owned facts
+<Grid columns={{ base: 1, md: 2 }}>
+  <Card title="Contact"><MetadataList items={contactFacts} /></Card>
+  <Card title="Billing"><MetadataList items={billingFacts} /></Card>
+</Grid>
+```
+
+Grid owns separation between the sibling subjects and their responsive columns. Each Card
+owns its header and body inset. For a resource browser, DataView already owns the filter/table
+frame: put a Heading and supporting Text beside that frame instead of wrapping it in another
+Card. The [resource workflow](reference-workflows.md) demonstrates a constrained parent;
+the detail workflow demonstrates a secondary table within an independent titled subject.
+
+Keep a record's command beside that record, a page command in the page header, and a
+selected-row command in the table's bulk-action seam. Filter toolbars communicate query
+state; export and create belong in the action slots. Applications decide destructive policy,
+field-per-row arrangements and permission boundaries.
+
+For server filtering, use `filtering.filterRows: ({ data }) => [...data]` when the server
+already matched the page. DataView's default filtering is local and can remove valid server
+matches whose search fields are absent from the visible columns. Use an app-owned cursor
+footer when totals are unknown; never invent a page count. Drop to DataTable when the app
+already owns the browser shell, filters and command placement.
+
+Selector variants serve different lifecycles: SuggestionsCombobox uses the generic lookup
+hook; AsyncCombobox accepts application-owned results; ResourceCombobox owns the ready
+single-resource fetching presentation. Use `scopeKey` on SuggestionsCombobox or ResourceCombobox when workspace or permission context changes without a
+query change. It invalidates lookup results, not the controlled selection. The application
+clears a value that is invalid in the new context.
+
+```bash
+node node_modules/themelia-ui/scripts/consumer/find-component.mjs "editable section" --context=existing-surface --context=editable --explain
+node node_modules/themelia-ui/scripts/consumer/find-component.mjs "resource selector" --context=changing-scope --json
+```
+
+Context matches are positive evidence. Uncurated exports remain visible with unknown
+context coverage; they do not become recommendations by omission.
+
 ## When to wrap, compose, or contribute
 
 - **Wrap** when the product needs a stable local name or defaults around one module.

package/.agents/skills/themelia-ui/references/forms.md

@@ -69,9 +69,10 @@ consumer on plain state never resolves react-hook-form.
 
 ## Field chrome
 
-`FormField` renders exactly **one** supporting line, resolved as `error || helperText ||
-hint`. They replace each other rather than stacking, so a field never grows or shifts as
-validation state changes. It also owns the wiring: it associates the label, points
+`FormField` renders at most **one** supporting message, resolved as `error || helperText ||
+hint`. They replace each other rather than stacking. A message can wrap, and adding or
+changing it can change field height; check long translated errors at narrow widths.
+It also owns the wiring: it associates the label, points
 `aria-describedby` at the supporting line, and sets `aria-invalid` on the control when there
 is an error, without overriding any of these that the caller set explicitly. Errors are
 announced politely (`role="status"`), so validation firing on each keystroke does not
@@ -80,6 +81,25 @@ interrupt typing.
 `FieldGroup` covers several controls sharing one label and one supporting line — a date
 range, a name split in two.
 
+## Sections and completion
+
+Use FormSection for an editable region inside a form, Card for an independent subject,
+and ContentBlock for supporting read-only prose. Flat FormSections retain region padding;
+an enclosing Stack can use `gap="none"` when that padding supplies the desired separation.
+FieldGroup supplies fieldset/legend semantics. Each child FormField still needs a distinct
+label. A section heading is not a field label.
+
+A resolved promise is not evidence that validation succeeded. ActionDialog normally closes
+after its confirmation callback resolves. Set `closeOnAsyncComplete={false}` when the app
+resolves with errors, and close controlled `open` only after explicit success. For a native
+form, use `formId` to associate the dialog's submit action with that form; avoid also invoking
+the mutation in `onConfirm`. Native constraint validation, the submit handler and domain
+validation then each have one owner. Prevent duplicate submissions while pending, retain
+drafts after rejection and associate errors with the relevant field or root region.
+
+See the complete [multi-section form and nested action](reference-workflows.md) sources.
+For the inset and gap contract, see [Structure and spacing](structure-and-spacing.md#use-the-two-spacing-roles).
+
 ## Generated forms
 
 When the fields come from a schema at runtime, use `features/schema-form`. When they are

package/.agents/skills/themelia-ui/references/framework-wiring.md

@@ -22,7 +22,9 @@ cells. Write it once:
 import type { LinkRenderer } from "themelia-ui/layout/sidebar"
 
 export const renderLink: LinkRenderer = ({ href, children, active, disabled, external, ...rest }) =>
-  disabled || !href ? <span {...rest}>{children}</span> : <AppLink to={href} {...rest}>{children}</AppLink>
+  disabled || !href ? <span {...rest}>{children}</span>
+    : external ? <a href={href} {...rest}>{children}</a>
+    : <AppLink to={href} {...rest}>{children}</AppLink>
 ```
 
 Return one element and spread the rest of the props onto it: they carry the class, the
@@ -50,6 +52,20 @@ async lifecycle; the application decides cache invalidation, retries, and error
 </ResourceIndexShell>
 ```
 
+## Lookup and navigation lifetimes
+
+Pass a stable `scopeKey` to ResourceCombobox, SuggestionsCombobox or useSuggestions when the lookup's workspace, locale or
+permission context changes. Changing callback identity alone does not refetch. A scope
+change aborts old work, hides old results/errors and refetches an eligible open query while
+retaining query, controlled value and open state. Late responses from an old scope cannot
+complete the current lookup. The app owns whether the selected id remains valid.
+
+Sidebar workspace disclosure keeps the mobile sheet open. A selected workspace marked
+`external: false` dismisses the sheet after selection; external destinations retain native
+target/rel behavior. Forward renderer props, including the click handler, to the real link.
+The app's router handles same-app addresses and preserves modifiers and new-tab gestures.
+See the [workspace reference](reference-workflows.md).
+
 ## Permissions
 
 Resolve authorization before constructing actions. Omit an action the user cannot perform;
@@ -58,16 +74,28 @@ through the module's tooltip or description seam.
 
 ## Translation
 
-Supply user-facing package copy through each component's `strings` prop. Keep product copy
+Supply component-owned copy through the selected API's documented `strings` prop. Passive
+components whose copy comes from children need no strings object. Keep product copy
 in application data or children. The default objects are exported so a locale can start
 from the complete shape rather than guessing keys; see [Internationalization](i18n.md).
 
 ## Server rendering and client boundaries
 
-Import server-pure formatting modules freely. Interactive modules carry their own
-`"use client"` boundary in the published entrypoint. Do not wrap the whole package in one
-client module: exact subpaths keep server-pure imports server-pure and optional peers
-isolated.
+Interactive and provider-dependent entrypoints carry `"use client"`, including
+`themelia-ui/primitives` and `themelia-ui/ui-provider`; passive modules such as
+`themelia-ui/base/structure` can remain server-pure. Inspect the exact published entrypoint
+rather than inferring its boundary from its name. In a React Server Components framework, a server component
+can render those client components with serializable props; callbacks, hooks and live
+controlled state belong in an application client component. A provider can receive server
+rendered children, so keep the boundary around the interactive region rather than the whole
+page. Check your framework's serialization rules for config containing functions or modules.
+
+Formatting helpers exported from `primitives` share its client boundary: do not call them
+from an RSC server component as if they came from a server-pure subpath. Format server data
+with the application's server utilities or render the corresponding display primitive.
+`themelia-ui/theming` exports pure derivation helpers without a client directive. Exact
+subpaths also keep optional peers isolated. Ordinary Node SSR can load and render the
+component modules; that does not make their exports server-callable in RSC.
 
 For CSP, portals, nested theme regions, and defaults, use
 [Provider and scoping](provider-and-scoping.md). Do not recreate provider context in an

package/.agents/skills/themelia-ui/references/i18n.md

@@ -5,8 +5,10 @@ overridable, and nothing in it inspects `navigator.language` or imports a transl
 
 ## Strings
 
-Each module exports a `*Strings` interface and a `default*Strings` object, and its
-components take a `strings` prop:
+Components that own visible or accessible copy document a `strings` prop; their modules
+export the matching `*Strings` interface and `default*Strings` object. Passive structures
+and components whose copy comes entirely from children need no strings object. Read the
+selected API rather than adding `strings` by analogy:
 
 ```tsx fragment — shape only, not a program
 <Copyable strings={{ copy: "Kopieren", copied: "Kopiert" }} value={apiKey} />

package/.agents/skills/themelia-ui/references/imports.md

@@ -7,7 +7,7 @@ siblings do not exist, because one specifier would pull an entire tier and every
 peer inside it. The root carries the provider and the display primitives, both peer-free.
 
 A component brings its own CSS in a bundled app. Pages with no bundler link `style.css`; see
-docs/learn/installation.md.
+[Installation](installation.md).
 
 ## general profile — 95 modules
 

package/.agents/skills/themelia-ui/references/installation.md

@@ -4,8 +4,9 @@
 npm install themelia-ui
 ```
 
-React 19 and `react-dom` are required peers. Everything else is optional and only pulled in
-by the module that needs it; see [Optional peers](#optional-peers).
+React 19 and `react-dom` are required peers. The package's regular dependencies install
+automatically; additional peer packages are optional and resolved only by the modules
+that need them. See [Optional peers](#optional-peers).
 
 ## Browser support
 
@@ -107,8 +108,8 @@ releases.
 
 ## Optional peers
 
-Every peer other than React is optional, and each is reachable only from the modules that
-use it: a consumer who never imports `features/map` never resolves Leaflet.
+Every peer other than `react` and `react-dom` is optional, and each is reachable only from
+the modules that use it: a consumer who never imports `features/map` never resolves Leaflet.
 
 The peer-to-module table is in [`docs/generated/imports.md`](imports.md).