themelia-ui 3.0.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,17 +13,33 @@ 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
    sufficient extension rung: prop → provider default → slot/render prop → composition →
    consumer CSS → application-owned component.
-5. Import the exact JavaScript subpath and exact module stylesheet.
+5. Import the exact JavaScript subpath; in a bundled app its CSS comes with it.
 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
@@ -44,11 +61,9 @@ These paths exist after installation and are the source of truth:
 | `node_modules/themelia-ui/docs/generated/components/INDEX.md` | module-by-module API references and recipes |
 | `node_modules/themelia-ui/docs/generated/component-index.json` | machine-readable discovery records |
 | `node_modules/themelia-ui/docs/generated/public-api.md` | every exported name and exact subpath |
-| `node_modules/themelia-ui/docs/generated/imports.md` | every JS/CSS import and optional-peer owner |
+| `node_modules/themelia-ui/docs/generated/imports.md` | every import and optional-peer owner |
 | `node_modules/themelia-ui/docs/generated/recipes.json` | machine-readable live-preview examples |
-| `node_modules/themelia-ui/src/styles/TOKENS.md` | exhaustive public theme-author contract |
-| `node_modules/themelia-ui/src/styles/FACTORS.md` | scale, spacing, density, and typography factors |
-| `node_modules/themelia-ui/src/styles/SCOPES.md` | boundaries where derived tokens recompute |
+| `node_modules/themelia-ui/src/styles/TOKENS.md` | the theme contract: every variable, its role, and what components compute from it |
 | `node_modules/themelia-ui/docs/generated/migration.md` | every renamed or removed name, token and utility, with what replaces it |
 | `node_modules/themelia-ui/scripts/consumer/codemod.mjs` | applies the mechanical half of an upgrade to your source |
 
@@ -67,11 +82,11 @@ 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, 386 attributed live recipes, and
-118 live preview routes by public symbol, module id, recipe title, preview route,
+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
-`publicImport`, `cssImport`, `apiDoc`, optional peers, dependencies, and alternatives.
+`publicImport`, `apiDoc`, optional peers, dependencies, and alternatives.
 Use `--explain` to see matched components and why they fit. Component guidance identifies
 curated decisions separately from module-level fallback; missing prop defaults are not inferred.
 <!-- /GENERATED:search -->
@@ -102,9 +117,9 @@ Selection rules:
 | Base (`base`) | 54 | one generic concept: text roles, controls, rows, passive structure | `themelia-ui/base/accordion` |
 | Layout (`layout`) | 9 | page and application shells | `themelia-ui/layout/app-shell` |
 | Features (`features`) | 24 | an owned interaction lifecycle — a context, a hook, a state machine | `themelia-ui/features/actions` |
-| Blocks (`blocks`) | 5 | an arrangement rendering a subject; the admin blocks make up the admin profile | `themelia-ui/admin/patterns/access` |
+| Blocks (`blocks`) | 5 | an arrangement rendering a subject; the admin blocks make up the admin profile | `themelia-ui/blocks/admin/access` |
 
-97 modules, 752 public components, 1070 exported symbols in total.
+97 modules, 752 public components, 1072 exported symbols in total.
 <!-- /GENERATED:tiers -->
 
 Dependencies flow downward:
@@ -134,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
 
@@ -152,21 +170,21 @@ leaflet. Reach for a module by its own subpath and the question never comes up.
 <!-- GENERATED:delivery by scripts/gen-agent-skill.mjs — do not edit between these markers. -->
 ```tsx compile
 import { Button } from "themelia-ui/base/buttons"
-import "themelia-ui/base/buttons.css"
 ```
 
-**The JavaScript imports no CSS.** A component whose module stylesheet is not imported
-renders unstyled.
+**A component brings its own CSS.** In a bundled app (Vite, webpack, Rspack, Next.js, React
+Router, Astro) importing the component is enough: its stylesheet arrives with its
+JavaScript, once, and a module the application never imports brings none. Do not also
+import `themelia-ui/style.css` or a module stylesheet from JavaScript; that loads the CSS twice.
 
-**The stylesheet is split per module.** 90 of 97 modules ship one; a module whose components draw nothing has none. Each module stylesheet imports
-`core.css` itself, so the tokens, themes, and cascade layer order arrive automatically.
-Import `core.css` on its own only when application CSS needs the token contract before
-any component stylesheet is loaded.
+**Server rendering with Vite needs one line.** Astro, React Router, TanStack Start and Vike
+list `themelia-ui` in `ssr.noExternal`; Astro renders the kit unstyled without it.
 
-`themelia-ui/style.css` is the deduplicated union of every sheet, for a consumer who would
-rather not track them. It is larger than what any one application uses.
+**No bundler:** link `themelia-ui/style.css`, which includes `core.css`. Node, Vitest and
+`require()` load the JavaScript with no CSS setup; Jest needs 29.4 or newer, with the package
+exempted in `transformIgnorePatterns`.
 
-Import consumer overrides after the kit. Its component rules are layered, so ordinary
+Consumer overrides need no ordering: the kit's component rules are layered, so ordinary
 unlayered app CSS wins without specificity tricks.
 <!-- /GENERATED:delivery -->
 
@@ -192,7 +210,7 @@ There are 15 optional peer packages. A consumer only needs the peers reachable f
 | `react-hook-form` | `features/sync`, `forms-rhf` |
 | `react-leaflet` | `features/map` |
 | `react-leaflet-markercluster` | `features/map` |
-| `recharts` | `base/chart`, `patterns/analytics` |
+| `recharts` | `base/chart`, `blocks/analytics` |
 <!-- /GENERATED:peers -->
 
 ## Provider, scopes, themes, and portals
@@ -224,15 +242,16 @@ export function ScopedPreview() {
 }
 ```
 
-Theme through the public contract in `node_modules/themelia-ui/src/styles/TOKENS.md`.
-The three factors are `--scale` (everything), `--density-scale` (spacing and control
-geometry, rounded to whole pixels) and `--text-scale` (type); the last two default to
-`--scale`. Set them on `:root`, with a `density` preset, or on a scope boundary; semantic
-colours are re-derived at each boundary, so override those through the provider or a scope. Component-level variables
-are implementation plumbing unless the public token reference explicitly promotes them.
+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). 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.
 
-Import application overrides after kit CSS. Kit component rules are layered, so ordinary
-unlayered consumer CSS wins without `!important`. Target stable documented `data-slot` or
+Kit component rules are layered, so ordinary unlayered consumer CSS wins whatever its order,
+without `!important`. Target stable documented `data-slot` or
 BEM hooks, and Base UI's state attributes (`data-open`, `data-checked`, `data-disabled`,
 `data-highlighted`, `data-popup-open`) for a state — not Radix's `[data-state="open"]`; never
 target CSS Module hashes. If the application uses Tailwind
@@ -267,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 |
@@ -278,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,9 +15,10 @@ 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 |
 
-A deprecated API introduced during a stable major remains available for that major with a
-named replacement and migration instructions. It is removed only in the next major unless
-security or correctness makes retaining it unsafe.
+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.
 
 A removal, a newly required member or an incompatible type change ships with a migration
 record: the migration reference (`node_modules/themelia-ui/docs/generated/migration.md`) names each one with its

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:
@@ -68,11 +72,8 @@ generic metadata, and an action without teaching the package what an invoice is:
 
 ```tsx compile
 import { Button } from "themelia-ui/base/buttons"
-import "themelia-ui/base/buttons.css"
 import { MetadataList } from "themelia-ui/base/display"
-import "themelia-ui/base/display.css"
 import { Page } from "themelia-ui/layout/page"
-import "themelia-ui/layout/page.css"
 
 type Invoice = { id: string; number: string; customerName: string; status: string; dueLabel: string }
 export function InvoiceDetail({ invoice, onCollectPayment }: {
@@ -111,10 +112,8 @@ callbacks, then open each linked module reference for the complete prop contract
 ### Dashboard
 
 ```tsx fragment — dashboard data and chart series come from the consuming application
-import { MetricGrid } from "themelia-ui/patterns/analytics"
-import "themelia-ui/patterns/analytics.css"
+import { MetricGrid } from "themelia-ui/blocks/analytics"
 import { Page } from "themelia-ui/layout/page"
-import "themelia-ui/layout/page.css"
 
 <Page header={{ title: "Overview", description: periodLabel }}>
   <MetricGrid metrics={metrics} variant="card" />
@@ -128,7 +127,6 @@ window, permission-filtered figures, and what clicking a metric means.
 
 ```tsx fragment — columns, filters, records, paging, and mutations are consumer-owned
 import { DataView, DataViewPagination } from "themelia-ui/features/data-view"
-import "themelia-ui/features/data-view.css"
 
 <DataView
   data={records}
@@ -148,13 +146,18 @@ 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
 import { FormActionsBar, FormField, FormSection, SubmitStateButton } from "themelia-ui/base/forms"
-import "themelia-ui/base/forms.css"
 import { Input } from "themelia-ui/base/text-inputs"
-import "themelia-ui/base/text-inputs.css"
 
 <FormSection title="Billing" description="Where invoices go.">
   <FormField label="Company" error={errors.company}>
@@ -171,7 +174,6 @@ adapter when React Hook Form already owns the state.
 
 ```tsx fragment — route matching and the router link renderer belong to the application
 import { AsideNavShell } from "themelia-ui/layout/settings"
-import "themelia-ui/layout/settings.css"
 
 <AsideNavShell
   title="Settings"
@@ -200,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.
 
@@ -218,15 +220,10 @@ the entered value; pending state prevents a second submission.
 ```tsx compile
 import { useState } from "react"
 import { Card, CardHeader, CardContent } from "themelia-ui/base/cards"
-import "themelia-ui/base/cards.css"
 import { FormField } from "themelia-ui/base/forms"
-import "themelia-ui/base/forms.css"
 import { Input } from "themelia-ui/base/text-inputs"
-import "themelia-ui/base/text-inputs.css"
 import { Button } from "themelia-ui/base/buttons"
-import "themelia-ui/base/buttons.css"
 import { Stack } from "themelia-ui/base/structure"
-import "themelia-ui/base/structure.css"
 
 export function RenameRecord({ initialName, save }: {
   initialName: string
@@ -248,7 +245,7 @@ export function RenameRecord({ initialName, save }: {
         catch { setError("Could not save. Your changes are still here; try again.") }
         finally { setPending(false) }
       }}>
-        <Stack gap="md">
+        <Stack gap="sm">
           <FormField label="Name" error={error}>
             <Input value={name} disabled={pending} onChange={(event) => setName(event.target.value)} />
           </FormField>
@@ -270,7 +267,6 @@ filtering contract to your query layer instead of filtering an already paged sub
 ```tsx compile
 import { useState } from "react"
 import { DataView, type DataViewProps } from "themelia-ui/features/data-view"
-import "themelia-ui/features/data-view.css"
 import { FilterType, FilterOperator, type ActiveFilter, type FilterConfig } from "themelia-ui/features/filters"
 
 type RecordRow = { id: string; name: string; status: string }
@@ -298,7 +294,6 @@ edge fade through the public prop instead of adding a local mask or a second scr
 
 ```tsx compile
 import { Tabs, TabList, Tab, TabPanel } from "themelia-ui/base/navigation"
-import "themelia-ui/base/navigation.css"
 
 export function SettingsTabs() {
   return <Tabs defaultValue="general">
@@ -330,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.