themelia-react-ui 1.0.0 → 1.0.2

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

@@ -0,0 +1,126 @@
+# Composition review and checks
+
+Use after selecting owners, or when auditing a screen. Read only the relevant
+workflow/declarations; this is a review aid, not a new design system.
+
+## Review the task and hierarchy
+
+- Can the user identify the subject, scope and next action? A contextual fact
+  may be repeated for a separate purpose, but should not compete with itself.
+- Do independent records, facts, metrics and editable fields use appropriate
+  owners? Inspect an existing feature before reconstructing its lifecycle.
+- Do primary commands have explicit emphasis and page/collection/record scope?
+  Keep bulk actions tied to selection. Secondary/destructive importance is semantic.
+- Do rows lead with identity and useful decision information? Preserve access
+  to hidden facts without forcing every fact into a tall identity stack.
+- Does each gutter, inset and sibling/copy gap have one owner? Review the whole
+  parent/child chain. A token-backed utility on the wrong owner can still drift.
+- Does the same composition remain readable with long copy, translations,
+  empty/missing values and narrow parent width? Zero and unavailable differ.
+
+These criteria allow different product layouts. Do not impose a universal card
+count, row-line limit, primary button count or one-column form rule.
+
+## Optional source checker
+
+The package ships a read-only script, not an npm bin/global CLI. It needs the
+consumer's TypeScript development dependency and Node matching the package engine:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/check-composition.mjs resources/js/pages resources/js/components
+```
+
+Pass explicit files/directories; `.tsx`, `.ts`, `.jsx` and `.js` are inspected.
+It resolves TypeScript from the app working directory and uses its adjacent
+versioned public index. A complete copied skill works too, after the installed
+identity check. It neither edits files nor installs dependencies. Add this
+command to app CI if useful; repository lint is not automatically installed.
+
+Errors cover unknown package entrypoints/symbols and statically detected overrides
+of protected Card/popup insets, Card badges in headerAction/headerStart rather
+than titleSuffix, control geometry/typography, fixed DisplayLabel/Badge
+roles, cross-role shell/inner radius replacements, display-copy margins, or
+attenuated shared focus rings on imported controls. Intentional nested bodies,
+circular owners and joined-edge corner resets retain their roles. Import ownership
+follows lexical bindings, preserving locally shadowed application components. Deprecated migration
+owners, nested framed subjects and repeated literal headings produce review
+warnings; warnings alone do not fail CI. Messages identify the owner and remedy.
+Standalone compact Cards and Page gutter removal also produce review warnings.
+Verified Card-owning Metric/card-grid, UsageCard and TaskCard compositions also
+participate in nested-surface and peer-gap review. Metric without its card variant,
+compact MetricGrid, flat TaskCard, ChartCard and Receipt do not establish a frame.
+Direct framed/default Card peers, including GridCell-wrapped peers, in a statically
+small Stack/Grid gap also warn; omitted gaps use the actual component defaults.
+Review visible ring clearance and the application's ordinary surface policy.
+Review the compact subject and actual parent inset; PageViewport supplies none.
+Recognizable metric cards, repeated fact rows and centered empty regions suggest
+Metric/MetricGrid, MetadataList/InlineStat or EmptyState. Lower-level Empty and
+modal anatomy suggest their complete workflow owners. These semantic guesses
+are contextual warnings: keep valid custom subjects, editable rows and modal
+lifecycles when the complete owner's contract differs. An arbitrary *Card name
+never establishes ownership; ChartCard and Receipt are useful counterexamples.
+Use existing app lint/typechecking for wider language, utility and accessibility
+coverage. The script is deliberately small and does not replace them.
+
+Coverage is limited to direct public imports, aliases/namespaces, native paragraph/
+heading copy and same-file static classes/styles/props. Dynamic expressions are reported as unresolved;
+cross-file wrappers, external CSS, render functions and runtime values require
+review. Do not treat an empty report as proof of complete compliance or taste.
+
+## Rendered and interaction evidence
+
+Source checks establish imports and known ownership violations. Separately inspect
+actual rectangles, wrapping, shared insets, title/action alignment and information
+weight at supported parent widths and light/dark scopes. Open relevant menus and
+overlays; a closed trigger cannot prove portal theming or popup geometry.
+
+Execute affected callbacks, keyboard/focus, cancellation, validation, pending
+and failure/retry states. Use deferred requests to observe pending behavior.
+Confirm accepted data changes and draft retention; a toast is only feedback.
+Compare before/after at the same conditions and record unverified limits.
+
+Treat the user's appearance feedback as an acceptance criterion. Reproduce the
+reported state at its actual width/theme and improve the responsible composition
+or shared recipe. Keep source findings, measurements and inspected-image judgment
+distinct: matching classes/radii and zero overflow do not establish a coherent
+appearance. Inspect borders, rings, clipping and settled transforms in the actual
+state. Compare the requested theme value before changing a shared default; an
+image should demonstrate that the correction addresses the visible complaint.
+
+## Application policy
+
+Keep a small app-owned reference linked from its agent instructions: name the
+shell/header/gutter owners, routing/query/form adapters, scope semantics,
+information priorities and relevant local tests. Link current representative
+pages. Preserve permissions, transport, translations and product-specific forms.
+Do not copy the package API manual or edit the packaged skill to encode local policy.
+
+When agent output is wrong, inspect installed/copied identity, whether the skill
+was loaded, its discovery results, the actual declarations/runtime, and competing
+app adapters/guides. An import-valid screen can still follow the wrong ownership
+rule. Check current source rather than strengthening every sentence into a ban;
+document concrete contradictions and fix the owning policy. Static checks cannot
+infer product meaning or prove which instructions an agent actually followed.
+
+Package declarations define supported props; this skill defines shared composition
+and anatomy; the app defines business meaning and page conventions. If a shared
+owner fails in a valid composition, isolate a reproduction and report the owning
+contract. Do not spread private selectors or copy the control to hide the issue.
+
+## When a valid composition looks wrong
+
+Compare the installed declarations, shipped CSS and copied skill version first.
+Test without the app reset when fonts, borders or list insets differ. Combine
+field affordances and vary density separately from spacing; inspect long copy
+in a narrow parent at a wide viewport too. Source checks cannot detect these.
+
+Prefer a minimal public-API reproduction over private descendant CSS. For example,
+use Metric's card variant for a navigable KPI with formatted value/trend instead
+of recreating its hierarchy with Card + Text. Use Heading's `size` for visual
+emphasis while `tag` keeps semantic level; its default admin scale is deliberate.
+A custom Card subject or an application-owned hero remains valid.
+
+Run discovery using both the task phrase and exact family/symbol. A zero result
+is not permission to invent an export: inspect public-api.json/declarations and
+report a missing capability. Static unknown spreads/classes remain unresolved;
+review them at runtime rather than treating an empty finding list as approval.

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

@@ -8,21 +8,50 @@ Use shadcn semantic surfaces/foregrounds: background, card, popover, primary, se
 
 tokens.json distinguishes 23 structural roots, advanced typography/status settings, and derived utility spellings. A utility is not another public variable. Keep overrides in one stylesheet at root or ThemeScope, without copying computed CSS into JavaScript.
 
-Default --radius is 1rem (16px). rounded-radius is the default throughout the package. rounded-inner is opt-in for nested bodies/items and derives at 0.6× (9.6px). Do not invent an outer/surface radius or enlarge an individual card based on padding. Circular avatars/dots remain intentional shapes.
+The default `--radius` is 0.75rem (12px). One public root drives two shared
+roles; component owners choose the role, so ordinary callers add no radius class.
+
+| Role | Owners | Default |
+| --- | --- | --- |
+| `rounded-radius` | Cards, popup/command shells and other outer surfaces | 12px |
+| `rounded-inner` | Inputs, buttons, select/facet triggers, collection/navigation rows and intentional nested bodies | 9px |
+
+Standalone controls retain the inner role; a complete nested Card retains its
+outer-shell role. Physical nesting does not select a different recipe.
+
+The inner role is `min(radius × 0.75, min(height-action, height-control) ×
+density-scale ÷ 4)`. The height bound keeps short controls restrained when an app
+increases the global radius; a 0.75 multiplier alone would still produce capsules.
+The smaller base height preserves a common inner radius when action and field
+heights differ. Density scales that bound once: the default roots at density
+0.875 yield 7.875px inner corners. Control size variants share the role; spacing
+scale and surface padding do not change it. Do not override the derived alias as
+another theme setting. Circular avatars/dots and joined-edge resets retain their
+explicit shape mechanics; Badge retains its own root-based recipe.
+
+CSS fits overlapping curves to the actual box, so computed values alone do not
+prove the visible shape. Inspect settled corners, borders, clipping and focus
+rings in opened surfaces. Change `--radius` at the theme boundary, rather than
+replacing individual components' owned corners.
 
 ```css
-/* After themelia-react-ui/style.css; no Tailwind build needed for overrides. */
+/* Intentional 40px controls, after style.css; overrides need no Tailwind build. */
 :root {
-  --radius: 1rem;
+  --radius: 0.75rem;
   --height-action: 2.5rem;
   --height-control: 2.5rem;
-  --surface-x: 1rem;
-  --surface-y: 1rem;
+  --surface-x: 1.25rem;
+  --surface-y: 1.25rem;
 }
 ```
 
 Action and editable-control heights are separate roles; keep roots equal for adjoining alignment. `--space-scale` multiplies structural gaps, inline insets and surface padding. `--density-scale` multiplies action/control height and collection block padding. Roots are unscaled measurements; do not pre-multiply and then apply the utility again.
 
+Both surface roots default to 1.25rem. At a 16px root font and space-scale 1,
+ordinary surface insets are 20px, compact insets are 10px and large insets are
+36px. Page's default large gutters inherit that same recipe. Row insets,
+control heights and copy gaps keep their independent roots.
+
 | Shared geometry | Root / derivation |
 | --- | --- |
 | Actions versus fields | `--height-action` versus `--height-control`; default size uses the root times density-scale |
@@ -40,6 +69,12 @@ Explicit portal containers take precedence over the nearest ThemeScope. Place th
 
 Apps using semantic utilities in their own JSX process themelia-react-ui/theme.css after Tailwind in a Tailwind v4 stylesheet. Compiled style.css styles shipped components but does not compile arbitrary app utility names. Keep app-owned classes namespaced and layout-focused.
 
+The package class merger recognizes token overrides only for advertised utilities and exact class spellings emitted by the library stylesheet, including their negative, important and responsive forms. A valid Tailwind alias such as `m-space-2xl` can still be absent from that stylesheet. Unshipped aliases preserve existing fallback classes; they do not receive package override semantics merely because an app's separate Tailwind build can generate them. Use the app's own merge configuration for additional app-compiled aliases.
+
+`ring` and `sidebar-ring` are focus roles tested at full strength. Preserve that
+strength and verify at least 3:1 against adjacent surfaces when overriding the
+theme; adding opacity can invalidate contrast even when the root color passes.
+
 ## Extend without drift
 
 Reuse existing color, text, action/control, row, surface or shell responsibilities first. An app token stays app-owned, not a package knob. New package tokens require multiple consumers, one owner/default/purpose, contract/docs updates and scoped behavior verification. Never expand the budget to fix one preview.
@@ -49,8 +84,18 @@ Use public structures/utilities for custom composition. Missing API seams should
 
 ## Copy rhythm
 
-Normal title/description gaps use `--gap-normal` (0.5rem); dense row and menu
-copy uses `--gap-dense` (0.25rem). Both multiply once by `--space-scale` and
+Normal title/description gaps use `--gap-normal` (0.25rem); dense row and menu
+copy uses `--gap-dense` (0.125rem). Both multiply once by `--space-scale` and
 inherit through ThemeScope and portaled surfaces. Control heights and insets
 remain separate. Use `textGap="normal" | "dense"` on headed surfaces and
 `gap="normal" | "dense"` on Stack/Grid instead of adding a description margin.
+
+## Independent geometry roles
+
+Use `--space-scale` for room around content and `--density-scale` for control
+heights. `--icon` and `--avatar` set media dimensions independently. Component
+`size` picks a shared sm/md/lg recipe; collection `density` changes row padding.
+Test these choices separately and in combination. Tables follow row insets,
+Cards and code/message bodies follow surfaces, and image containment uses generic
+spacing. Foundation directional spacing utilities ship with style.css and use
+the same seven steps as gaps; generated spellings are not new theme roots.

package/docs/consumer-skill/references/tokens.json

@@ -1,6 +1,6 @@
 {
   "package": "themelia-react-ui",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "structural": [
     {
       "name": "--space-scale",
@@ -14,12 +14,12 @@
     },
     {
       "name": "--gap-normal",
-      "default": "0.5rem",
+      "default": "0.25rem",
       "purpose": "Vertical rhythm between titles and structural descriptions."
     },
     {
       "name": "--gap-dense",
-      "default": "0.25rem",
+      "default": "0.125rem",
       "purpose": "Vertical rhythm between row titles and compact supporting copy."
     },
     {
@@ -49,12 +49,12 @@
     },
     {
       "name": "--surface-x",
-      "default": "1rem",
+      "default": "1.25rem",
       "purpose": "Default inline inset for cards and multi-content surfaces."
     },
     {
       "name": "--surface-y",
-      "default": "1rem",
+      "default": "1.25rem",
       "purpose": "Default block inset for cards and multi-content surfaces."
     },
     {
@@ -120,11 +120,11 @@
   ],
   "radius": {
     "name": "--radius",
-    "default": "1rem",
-    "purpose": "Default corners throughout the package; opt-in nested corners derive from this root.",
+    "default": "0.75rem",
+    "purpose": "Shared 8px corners keep short controls rectangular; nested corners derive from this root.",
     "defaultUtility": "rounded-radius",
     "innerUtility": "rounded-inner",
-    "innerFormula": "calc(var(--radius) * 0.6)"
+    "innerFormula": "min(calc(var(--radius) * 0.75), calc(min(var(--height-action), var(--height-control)) * var(--density-scale) / 4))"
   },
   "advanced": [
     "--font-heading",
@@ -256,7 +256,175 @@
       "gap-x-normal",
       "gap-x-dense",
       "gap-y-normal",
-      "gap-y-dense"
+      "gap-y-dense",
+      "pt-space-2xs",
+      "pt-space-xs",
+      "pt-space-sm",
+      "pt-space-md",
+      "pt-space-lg",
+      "pt-space-xl",
+      "pt-space-2xl",
+      "pb-space-2xs",
+      "pb-space-xs",
+      "pb-space-sm",
+      "pb-space-md",
+      "pb-space-lg",
+      "pb-space-xl",
+      "pb-space-2xl",
+      "pl-space-2xs",
+      "pl-space-xs",
+      "pl-space-sm",
+      "pl-space-md",
+      "pl-space-lg",
+      "pl-space-xl",
+      "pl-space-2xl",
+      "pr-space-2xs",
+      "pr-space-xs",
+      "pr-space-sm",
+      "pr-space-md",
+      "pr-space-lg",
+      "pr-space-xl",
+      "pr-space-2xl",
+      "ps-space-2xs",
+      "ps-space-xs",
+      "ps-space-sm",
+      "ps-space-md",
+      "ps-space-lg",
+      "ps-space-xl",
+      "ps-space-2xl",
+      "pe-space-2xs",
+      "pe-space-xs",
+      "pe-space-sm",
+      "pe-space-md",
+      "pe-space-lg",
+      "pe-space-xl",
+      "pe-space-2xl",
+      "m-space-2xs",
+      "m-space-xs",
+      "m-space-sm",
+      "m-space-md",
+      "m-space-lg",
+      "m-space-xl",
+      "m-space-2xl",
+      "mx-space-2xs",
+      "mx-space-xs",
+      "mx-space-sm",
+      "mx-space-md",
+      "mx-space-lg",
+      "mx-space-xl",
+      "mx-space-2xl",
+      "my-space-2xs",
+      "my-space-xs",
+      "my-space-sm",
+      "my-space-md",
+      "my-space-lg",
+      "my-space-xl",
+      "my-space-2xl",
+      "mt-space-2xs",
+      "mt-space-xs",
+      "mt-space-sm",
+      "mt-space-md",
+      "mt-space-lg",
+      "mt-space-xl",
+      "mt-space-2xl",
+      "mb-space-2xs",
+      "mb-space-xs",
+      "mb-space-sm",
+      "mb-space-md",
+      "mb-space-lg",
+      "mb-space-xl",
+      "mb-space-2xl",
+      "ml-space-2xs",
+      "ml-space-xs",
+      "ml-space-sm",
+      "ml-space-md",
+      "ml-space-lg",
+      "ml-space-xl",
+      "ml-space-2xl",
+      "mr-space-2xs",
+      "mr-space-xs",
+      "mr-space-sm",
+      "mr-space-md",
+      "mr-space-lg",
+      "mr-space-xl",
+      "mr-space-2xl",
+      "ms-space-2xs",
+      "ms-space-xs",
+      "ms-space-sm",
+      "ms-space-md",
+      "ms-space-lg",
+      "ms-space-xl",
+      "ms-space-2xl",
+      "me-space-2xs",
+      "me-space-xs",
+      "me-space-sm",
+      "me-space-md",
+      "me-space-lg",
+      "me-space-xl",
+      "me-space-2xl",
+      "top-space-2xs",
+      "top-space-xs",
+      "top-space-sm",
+      "top-space-md",
+      "top-space-lg",
+      "top-space-xl",
+      "top-space-2xl",
+      "bottom-space-2xs",
+      "bottom-space-xs",
+      "bottom-space-sm",
+      "bottom-space-md",
+      "bottom-space-lg",
+      "bottom-space-xl",
+      "bottom-space-2xl",
+      "left-space-2xs",
+      "left-space-xs",
+      "left-space-sm",
+      "left-space-md",
+      "left-space-lg",
+      "left-space-xl",
+      "left-space-2xl",
+      "right-space-2xs",
+      "right-space-xs",
+      "right-space-sm",
+      "right-space-md",
+      "right-space-lg",
+      "right-space-xl",
+      "right-space-2xl",
+      "start-space-2xs",
+      "start-space-xs",
+      "start-space-sm",
+      "start-space-md",
+      "start-space-lg",
+      "start-space-xl",
+      "start-space-2xl",
+      "end-space-2xs",
+      "end-space-xs",
+      "end-space-sm",
+      "end-space-md",
+      "end-space-lg",
+      "end-space-xl",
+      "end-space-2xl",
+      "inset-space-2xs",
+      "inset-space-xs",
+      "inset-space-sm",
+      "inset-space-md",
+      "inset-space-lg",
+      "inset-space-xl",
+      "inset-space-2xl",
+      "inset-x-space-2xs",
+      "inset-x-space-xs",
+      "inset-x-space-sm",
+      "inset-x-space-md",
+      "inset-x-space-lg",
+      "inset-x-space-xl",
+      "inset-x-space-2xl",
+      "inset-y-space-2xs",
+      "inset-y-space-xs",
+      "inset-y-space-sm",
+      "inset-y-space-md",
+      "inset-y-space-lg",
+      "inset-y-space-xl",
+      "inset-y-space-2xl"
     ],
     "states": [
       "text-link-color",

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

@@ -8,16 +8,93 @@ The [example manifest](../examples/manifest.json) owns filenames, exported compo
 
 [AccountIndex](../examples/index-table.tsx) exports `AccountIndex`, `AccountIndexProps`, `AccountRow` and `AccountIndexState`. Props are `state`, `onRetry`, `hrefFor(record)` and `onNavigate(href)`. The app drives the discriminated state: `loading`, `error` with a message, or `ready` with records. An empty ready collection renders the table's empty state. `onRetry` starts your loader; it must update app state through loading to ready/error. Stable row IDs belong to the records.
 
-This recipe uses `themelia-react-ui/features/table`, so install `@tanstack/react-table` as an optional peer. Card frames the page; the nested table uses `surface="flat"`. A row action calls your navigation callback with your URL; `href` alone on a table action does not navigate. Supply your router callback or ordinary browser navigation. The library neither requests records nor chooses routes.
+This recipe uses `themelia-react-ui/features/table`, so install `@tanstack/react-table` as an optional peer. Card frames an independent Accounts subject; the nested table uses `surface="flat"`. For a primary route collection use its own native table surface, as in the scoped directory below. A row action calls your navigation callback with your URL; `href` alone on a table action does not navigate. Supply your router callback or ordinary browser navigation. The library neither requests records nor chooses routes.
 
 Verify loading, empty refresh, failure/retry and ready records. Open the row menu with pointer and keyboard, activate Open account, and assert the requested URL. Check narrow overflow and email-link behavior. If you need a presentational table without TanStack features, discover `themelia-react-ui/base/table` and inspect its separate declaration.
 
+`enableResizing` enables pointer and keyboard separators on individual/grouped
+headers. Arrow keys follow inherited text direction; Home/End use leaf minimums
+and explicit maximums from your column definitions. The table owns its one named
+scroll region. Verify grouped widths, sticky header rows and first-column behavior
+with real overflow in both directions, rather than adding another focusable wrapper.
+
+## Comment attachments
+
+`Comments` and `CommentComposer` announce attachment validation/upload errors.
+Use their existing attachment error `strings` for localization. Headless
+`useAttachmentUpload` accepts those same keys through `strings`; render feedback
+from `onError` in your own composer. Failed chips retain retry/remove actions.
+Reset/removal aborts pending uploads; the app owns transport and persistence.
+
 ## Detail and framing
 
 [AccountDetail](../examples/detail.tsx) exports `AccountDetail`, `AccountDetailProps` and `AccountDetailRecord`. Supply `account`, `onEdit(id)` and `onBack()`. Card owns the frame/header/body/footer; Name, Email, Date, Money and Value own formatting and missing-value fallbacks. `balanceMinor` uses `Money unit="minor"`; currency and date values come from the app.
 
 No optional peers are needed. The app supplies the loaded record and owns navigation, locale/provider defaults and permissions. Verify missing email/date/balance, a real minor-unit amount, Edit/Back callbacks, and the one-column mobile/two-column desktop composition in light/dark themes.
 
+## Scoped directory
+
+[ScopedDirectory](../examples/scoped-directory.tsx) demonstrates a primary route
+collection. Page owns Contacts, the fixed business context and the explicit
+primary New contact command. DataTable owns the surface; FilterLayout occupies
+`topbarContent`, optional export occupies `topbarEnd`, and Open contact is a row
+action. ResourceCell owns identity, shared small secondary Text supplies role,
+and Email owns formatting. Other operational facts belong in the contact detail
+reached by `onOpen`; the example does not append every fact to compact identity.
+
+The optional `compact` prop is an app presentation decision from available parent
+width. It keeps email reach in the identity cell and omits the comparison Email
+column, preserving one copy and reachable row actions. This deliberately retains
+one task-critical fact; other metadata stays in detail. Choose the threshold
+from actual content and work-region measurements, not a universal library setting.
+
+The app supplies `scope`, discriminated `state`, controlled `filters`, navigation
+and loading callbacks. `onQueryChange({ scopeId, filters })` preserves fixed
+business context even when criteria clear. It does not request records itself.
+The recipe removes a blank `q` search criterion without normalizing unrelated
+filter types. Native search can emit an empty string; the app owns query meaning.
+The app updates filters/state, ignores stale responses and preserves scope/query
+in pagination URLs. A criteria-driven business selector would be a different
+product contract. The recipe's English labels are example copy: adapt labels,
+criteria and component `strings` for app translation and permissions.
+
+Strict imported declarations require the manifest's optional peers. DataTable
+sorting is disabled because the app's server owns query order. Loading/error
+feedback occupies the empty result region while query context remains mounted;
+accepted records replace it. Use the public loading/preview owner if retaining
+previous results is required by your app. Avoid stale pagination metadata during
+loading/errors. Run the same query with loading, failure, retry and empty results.
+
+Verify one contextual lead, primary command, query/clear scope retention,
+row-menu navigation, server page callbacks and long-name/mobile containment.
+Opening a record preserves access to supporting facts. Integrated queries and
+separate query regions are both supported; choose by task and keep one owner.
+
+Keep DataTable column/action definitions stable when unrelated parent feedback
+changes. Changing a cell renderer's identity can remount its menu trigger and
+lose return focus. This recipe memoizes row actions by `onOpen`; the app keeps
+that callback stable when its meaning is unchanged. Stabilize these lifecycle
+inputs deliberately, not every object. A real record/scope change can replace
+definitions; the app then chooses appropriate destination focus.
+
+## Single resource page
+
+Use `Page`, `PageHeader` and `PageActions` from `themelia-react-ui/layout/page`
+for the record route's identity, back navigation, content bounds and commands.
+The [layout recipe](../examples/app-layout.tsx) demonstrates that route boundary;
+the [detail recipe](../examples/detail.tsx) demonstrates an independently framed
+record subject with MetadataList and value primitives. Decide whether the record
+needs that independent Card before nesting it under Page. Avoid repeating the
+route heading just to frame the same facts. Page owns gutters; PageViewport owns
+scrolling only. App navigation, record loading/missing/error/retry, permissions,
+edit and delete callbacks remain application responsibilities.
+
+Use `WorkspaceLayout` from `themelia-react-ui/layout/workspace` when independently composed record header,
+sidebar/main/rail regions are needed; inspect `features/resource` for complete
+resource coordination. A single record does not automatically need either.
+Read [layout composition](composition.md#application-layouts) for boundary and
+parent-width behavior, then the exact selected declaration for its current props.
+
 ## Validated editing
 
 [AccountEdit](../examples/edit.tsx) exports `AccountEdit`, `AccountEditProps` and `AccountEditValue`. Supply `initial`, `onSave(value): Promise<AccountEditValue>` and `onCancel()`. Mount with `key={initial.id}` when switching records. The draft is local to that mount; resetting the same record's draft deliberately also requires a new key or your own controlled adaptation.
@@ -37,3 +114,54 @@ Your delete callback owns persistence and record removal. Reject failures instea
 Verify open/title/description, trapped keyboard focus, Cancel/Escape without a deletion callback, pending dismissal prevention, rejected callback with an open error, retry and successful closure, exactly one backend effect, and trigger focus restoration. Check the opened error dialog in dark/mobile as well as light/desktop. Do not infer these interactions from typechecking or screenshots.
 
 The existing [AccountComposition](../examples/composition.tsx) remains a basic Card/ActionDialog composition with `save(name): Promise<void>`. Its callback must reject on failure; the app owns persistence. The four recipes above add progressive collection/detail/edit/delete ownership without changing that example's contract.
+
+## Task summaries, usage and inline editing
+
+[Workspace summary](../examples/planning-usage-edit.tsx) composes three focused
+owners. `TaskCard` from `themelia-react-ui/blocks/planning` owns the explicit Card
+surface, completion summary, disclosure and controlled subtask proposals.
+Update `items` after `onItemCompletedChange`; supply each item's `busy` or
+`error` from your persistence lifecycle. Workflow status, due-date formatting,
+assignment and Open navigation remain application data/callbacks.
+
+Click passive header content or use the native caret (pointer, Enter or Space)
+to request expansion. Both respect `expanded`/`onExpandedChange` and `disabled`;
+header clicks focus the caret. Subtask and footer actions remain independent.
+The block owns the segmented progress drawing, completion strikethrough and
+compact checklist insets. Its progress value follows accepted `items`, including
+undo; workflow status stays separate. Reduced motion disables the ring animation.
+
+`UsageCard` from `themelia-react-ui/blocks/analytics/usage-card` is a standalone
+quota/analytics composition with no optional chart dependency. Supply matching
+`data`, `period` and `status` after `onPeriodChange`; cancel or ignore stale
+application requests. `limit: null` means unlimited, omitted limits or values
+mean unavailable, and zero is real data. Category percentages describe shares
+of reported usage; bounded graphics never hide actual over-quota amounts.
+Daily data is chronological application data with text equivalents. The block
+owns no subscription or billing requests; `footerAction` is application content.
+
+`InlineEdit` from `themelia-react-ui/base/inline-edit` uses our native Input or
+Textarea. Supply `onSave(value, { signal })` for asynchronous persistence and
+update a controlled saved value through `onValueChange`. Required/validation
+checks apply when saving a draft. Parent forms serialize the committed value
+through `name`; they own validation of their complete stored data. Enter saves
+a single line, Control/Command Enter saves multiline text, and Escape cancels.
+Cancellation invalidates late UI results and aborts the supplied signal; the
+application owns actual transport and server effects. Read-only display stays
+passive. Use Card at a composition boundary for a framed field section.
+
+Display and editing share the Input frame and `size`, `invalid`, `loading`,
+`clearable`, `onClear` and `showCharacterCount` APIs. The stable field/action
+grid transitions width and honors reduced motion; multiline actions form a
+centered column. Use `inputProps`/`textareaProps` for native editor attributes,
+adornments, resizing and control-specific strings. State/value/ref/form ownership
+stays with InlineEdit. Native constraints run on Save; uncommitted controls are
+isolated from the parent form. External loading retains a draft while disabling
+edits/save, and leaves cancellation available.
+
+The field/action gap uses the existing `lg` spacing step; the action group uses
+`xs`. Single-line actions form a horizontal pair and multiline actions a centered
+column. Keep these library-owned controls and geometry instead of replacing
+them with app-styled fields. Verify cancellation during persistence, retained
+drafts after rejection, native constraints, committed FormData, controlled
+expansion, checkbox/Open independence and async period retry in your app.

package/docs/consumer-skill/scripts/check-composition.mjs

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { validateIndex } from './discovery.mjs';
+import { analyzeComposition } from './composition-policy.mjs';
+
+try {
+  const targets = process.argv.slice(2);
+  if (!targets.length || targets.some(target => target.startsWith('-'))) throw new Error('Pass explicit source files/directories; no flags or automatic app-wide scan.');
+  const requireFromApp = createRequire(path.join(process.cwd(), 'package.json'));
+  const ts = requireFromApp('typescript');
+  const index = validateIndex(JSON.parse(fs.readFileSync(new URL('../references/public-api.json', import.meta.url), 'utf8')));
+  const files = new Set();
+  function collect(target) {
+    const info = fs.lstatSync(target);
+    if (info.isSymbolicLink()) throw new Error(`Use a real source path instead of a symlink: ${target}`);
+    if (info.isDirectory()) {
+      for (const entry of fs.readdirSync(target).sort()) if (!['node_modules', '.git', 'dist', 'build'].includes(entry)) collect(path.join(target, entry));
+    } else if (/\.[jt]sx?$/.test(target) && !/\.d\.ts$/.test(target)) files.add(path.resolve(target));
+  }
+  targets.forEach(collect);
+  if (!files.size) throw new Error('No supported source files found in the supplied paths.');
+  const reports = [...files].sort().map(filename => analyzeComposition(fs.readFileSync(filename, 'utf8'), { filename, index, ts }));
+  const findings = reports.flatMap(report => report.findings);
+  const errors = findings.filter(finding => finding.severity === 'error').length;
+  process.stdout.write(JSON.stringify({ package: index.package, version: index.version, files: files.size, errors, warnings: findings.length - errors, findings, unresolved: reports.flatMap(report => report.unresolved), limits: 'Source analysis only: recognized imports and same-file static JSX. External CSS, cross-file wrappers and dynamic values require review. No rendered, interaction, visual-acceptance or production-readiness verdict.' }, null, 2) + '\n');
+  process.exitCode = errors ? 1 : 0;
+} catch (error) {
+  process.stderr.write(`check-composition: ${error.message}\nRun from the consumer app with its TypeScript development dependency installed.\n`);
+  process.exitCode = 1;
+}