themelia-react-ui 2.0.3 → 2.0.5

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

@@ -5,16 +5,38 @@ work. Read only the relevant workflow/declarations; this is not a new design sys
 
 ## Review the task and hierarchy
 
+For a new or substantially repaired screen, review the
+[screen decisions](screen-decisions.md) against the actual result. Identify the
+user's decision, leading subject, visible versus overflow actions, navigation
+reason and surface/inset owners. The answer should explain this screen, not
+just name components or repeat an archetype.
+
 - 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.
+- Does the subject cover the entity parts relevant to the task, such as order
+  lines and selected variants, product options/variant combinations, or payment
+  allocations? State missing contracts and omitted scope. Neither a summary of
+  top-level fields nor a library feature's existence proves app coverage.
 - 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.
+- Do comparisons, allocations, dependencies and exceptions stay close to the
+  facts and commands they affect? Could the user make the business decision
+  without reconstructing relationships across generic cards? An existing block
+  is a good fit when its meaning and arrangement fit; an app-owned subject may
+  combine public parts and JSX when the data needs a different structure.
 - 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.
+- Do flat and painted peer regions align at their intended content edges?
+  Transparency does not remove Card padding. Does mobile reading order lead
+  with the operational subject rather than burying it after long evidence?
+- Do table headers, main values and supporting cell copy share an intentional
+  alignment? Inspect custom primitives inside cells; their own alignment and
+  inline/block defaults can override the cell. Using the right table owner
+  does not validate the caller's renderCell content.
 - Does the same composition remain readable with long copy, translations,
   empty/missing values and narrow parent width? Zero and unavailable differ.
 
@@ -24,21 +46,28 @@ one solid primary command per page or surface, so the next action stays obvious.
 
 ## Done means
 
-UI work is done when the source checker below reports no errors on the files you
-changed, and the app's typecheck, lint and tests then pass. Run the checker, fix
+UI work is complete only with three separate proofs: source/API checks, inspected
+rendered appearance and executed interactions. A correct but confusing hierarchy
+or inappropriate action/surface choice is unfinished even when all checks pass.
+Inspect one representative subject before replicating it across a screen. The source checker below must
+report no errors on changed files, and the app's typecheck, lint and tests must
+pass. Inspect the actual narrow/wide and light/dark states relevant to the change,
+including opened surfaces; execute the affected callbacks, keyboard/focus and
+error/retry paths. Record any missing proof as an unverified limit. Run the checker, fix
 the owner or prop each finding names, and run it again; after three rounds, stop
 and report what remains. Warnings are review findings: fix each one or keep it
 with a reason. This is the agent's completion condition, not the build's; app CI
 may stay non-blocking on warnings. The [project instructions
 block](agents-md.md) states the same condition in the app's `AGENTS.md`.
 
-Hand back five lines, so a skipped check is visible:
+Hand back a short evidence record, so skipped checks and missing proof are visible:
 
 1. Owners used for the route, its commands and each data region.
 2. Checker: run or not run, with its error and warning counts.
 3. Typecheck, lint and tests: each run or not run, and why.
 4. Kept warnings, each with file:line and its reason.
-5. States covered or missing: loading, empty, error, disabled and validation.
+5. Rendered: widths/themes/states measured and images actually inspected, with judgment.
+6. Interactions: actions and resulting states executed, including relevant focus, cancellation, loading, error/retry and validation; list missing coverage.
 
 ## Source checker
 
@@ -58,7 +87,7 @@ 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
+roles, cross-role surface/default radius replacements, display-copy margins, or
 redrawn focus indicators (another ring width, offset or halo strength) 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. Imports of
@@ -75,9 +104,22 @@ disabled 50% treatment remain valid; component disabled props keep that dimming
 with its owner.
 
 Standalone compact Cards and Page gutter removal also produce review warnings.
+`uncontained-table-in-card` flags a table in a padded Card: place DataTable in
+the layout, or deliberately use Card padding="none" and a flat table.
+`detached-filter-layout` recommends DataTable topbarContent for a sibling filter
+strip, or DataView for the complete workflow. `wide-single-column-form` suggests
+Page narrow for a simple form lacking explicit width or aside. These contextual
+warnings follow qualified import bindings; unrelated same-name components are
+not evidence. Deprecated resource shells use the existing deprecated-owner
+warning and direct new routes to Page.
 Buttons placed in a Page or PageHeader `actions` region warn as well: pass
 commands as `primaryAction` and ordered `secondaryActions` so the header owns
 their emphasis, size and overflow. Non-command controls stay valid there.
+For PageHeader's `slots.actions`, wrapping or returning the callback's
+`defaultContent` retains that command behavior; a full replacement owns its
+keyboard, overflow and action semantics. Inspect the compact menu below 40rem of
+header width, including in a narrow parent on desktop: every command, including
+primary, belongs in one More actions menu.
 A Page with more than one solid primary command, counting `header.primaryAction`
 and every Button with `tone="primary"` and no other style, warns as well. Overlays own
 their own primary command and are not counted. Raw palette classes such as

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

@@ -0,0 +1,93 @@
+# React Hook Form workflows
+
+Use `react-hook-form` for form state in create/edit pages, settings and overlays. Import chrome from `themelia-react-ui/base/forms`, text controls from `base/text-inputs`, choices from `base/choice-inputs`, dates from `base/date-pickers` and structured values from `base/value-inputs`. RHF is optional at package level, but the whole `base/forms` family requires its peer, including presentation-only FormField imports. A schema resolver is an application choice, not another required library dependency.
+
+## Screen and state ownership
+
+For expandable editing sections, inspect compound Accordion before rebuilding
+Card + Collapsible. The [retained section recipe](../examples/editable-sections.tsx)
+uses multiple expansion, validation badges and AccordionContent keepMounted.
+Keep one stable app-owned form and open an invalid section before focusing its
+field. Controlled form state retention and field DOM retention are separate
+contracts; see [disclosure composition](custom-composition.md#disclosure-sections).
+
+The complete [order edit page](../examples/rhf-edit-page.tsx) composes:
+
+`Page render={<form ... />}` owns the native form, containing `DirtyStateBanner / ErrorSummary → TwoColumnLayout → FormSection → ControlledFormField → sticky FormActionsBar / SubmitStateButton`.
+
+Page owns the route title/gutters and TwoColumnLayout owns peer rhythm. FormSection owns its surface and field gaps; do not wrap a framed FormSection in another Card. Inside an already padded boundary, use `surface="flat" padding="none"`. Inside an unpadded boundary, a flat FormSection keeps its ordinary inset; flat surface alone does not remove padding. `handleSubmit` validates and awaits persistence. `isSubmitting` drives the submit button and disabled fields; `isDirty` drives dirty feedback and pristine submit protection. An in-flight ref also blocks duplicate same-tick requests. Native form validation is disabled in these RHF examples so the schema/rules produce one consistent error source.
+
+Page forwards `render` to its existing Container, so rendering it as the form preserves one width, gutter and query-boundary owner. Its body already spaces direct subjects; no extra Container or Stack is needed around the layout and action bar. `TwoColumnLayout adaptTo="container"` adapts to that Page width. A standalone form outside Page needs its own deliberate query boundary when it selects container adaptation.
+
+Use `useFieldArray`'s stable `field.id` as the React key, preserve names such as `lines.${index}.quantity`, and set complete append defaults. Derive totals from `useWatch`; do not persist a second total that can drift. Collect nested client/server errors into ErrorSummary while keeping each field's local message. Use `setFocus` or summary links for focusable controls when the app's error-summary design requires it.
+
+Mount an editor with `key={record.id}` when switching records. `defaultValues` establishes the saved baseline. On accepted success call `reset(authoritativeSavedValues)` to clear dirty state and keep server normalization. `reset()` discards to that baseline. Failed validation, transport failure or cancellation keeps the draft. Do not reset on every background cache refresh. If the product allows editing during a request, reconcile the accepted response with later edits explicitly; these recipes disable editing while saving.
+
+## Typed control bindings
+
+[TypedControlBindings](../examples/rhf-bindings.tsx) typechecks every supported binding without `any`, control casts or a generic spread adapter. A public control's event contract is part of its API:
+
+| Control | Controlled state | Change and RHF focus/touch binding |
+| --- | --- | --- |
+| Input / Textarea | `value: string` | `onValueChange(value)` → `field.onChange`; `ref`, `onBlur` |
+| Select | `value: string` | `onValueChange(value)` → `field.onChange(value ?? '')`; trigger `ref`, `onBlur` |
+| Switch / Checkbox | `checked: boolean` | `onValueChange(checked)` → `field.onChange`; `ref`, `onBlur` |
+| ToggleField / SwitchCard | `value: boolean` | `onValueChange(checked)`; `controlRef`, `onBlur`; their own label owns the control name |
+| DatePicker (single) | `value: Date \| undefined` | `onValueChange(output)` → `field.onChange(output.date ?? null)`; `triggerRef`, `onBlur` |
+| DateTimeInput | ISO `value: string \| undefined` | `onValueChange(value)` → `field.onChange(value ?? '')`; `triggerRef`, `onBlur` |
+| PhoneInput | `value: string` | native `onChange(event.target.value)`; input `ref`, `onBlur` |
+| TagsInput | `value: string[]` (or typed objects) | `onValueChange(values)`; `inputRef`, `onBlur` |
+| SliderField (public slider name) | scalar `value: number` | `onValueChange(value)`; `inputRef`, `onBlur` |
+| ColorInput | `value: string` | `onValueChange(value)`; input `ref`, `onBlur` |
+
+For numeric Input fields normalize `event.target.valueAsNumber` according to the schema (an empty field is NaN); keep numeric validation explicit. Date-only fields need an application serialization policy; do not turn a local calendar date into a UTC instant accidentally. DateTimeInput uses ISO instants. Use `modal={false}` on pickers inside modal forms to avoid competing focus traps.
+
+ControlledFormField accepts a ReactNode error override or a name-based error getter, falling back to RHF validation. Its render callback's error argument remains string/undefined for compatibility. A direct supported control receives the generated label/control ID and supporting-text association automatically; omit routine `htmlFor`/`id` pairs. Each mount stays unique even when forms share field names. ToggleField and SwitchCard own their visible labels and forward the automatic supporting description to their editable control; omit an outer duplicate label.
+
+Compound children own their nested association. SliderField's `id` and forwarded `ref` name its group, while `inputRef` names the native range. The binding recipe uses visible copy with an ID, `aria-labelledby` on SliderField and `supportingTextId`/`aria-describedby` for its hint or error. Keep explicit IDs per mount when a passive wrapper separates chrome from the editable control; do not point `htmlFor` at a group or infer one common ref target across control families.
+
+## Transport lifecycle
+
+The app owns transport. RHF's submit callback must return a Promise spanning the complete request; otherwise `isSubmitting` drops early and repeated submissions become possible. The [callback bridge](../examples/rhf-transport.tsx) records success/errors/cancellation, then settles only from `onFinish`. It has no framework import or runtime dependency.
+
+For Laravel/Inertia, adapt the application's typed router and page props at this seam:
+
+```tsx
+const submit = form.handleSubmit(async values => {
+  const result = await awaitCallbackSave(values, (data, lifecycle) => {
+    router.put(`/orders/${order.id}`, data, {
+      preserveScroll: true,
+      onSuccess: page => lifecycle.onSuccess(readSavedOrder(page)),
+      onError: lifecycle.onError,
+      onCancel: lifecycle.onCancel,
+      onFinish: lifecycle.onFinish,
+    });
+  });
+  if (result.ok) form.reset(result.values);
+  else {
+    applyServerErrors(form.setError, result.errors, {
+      fields: ['reference', 'email', 'notes', 'priority', 'notify',
+        ...values.lines.flatMap((_, index) => [
+          `lines.${index}.product` as const,
+          `lines.${index}.quantity` as const,
+          `lines.${index}.priceMinor` as const,
+        ])],
+    });
+    if (result.message) form.setError('root.server', { message: result.message });
+  }
+});
+```
+
+`router`, `order` and `readSavedOrder(page)` belong to the app; readSavedOrder validates/reads its typed authoritative response. Import `applyServerErrors` from `themelia-react-ui/base/forms` and `awaitCallbackSave` from the copied bridge. The helper accepts unknown payloads, maps only string/string-array messages to an explicit typed FieldPath allowlist, and sends unknown keys to `root.server`. Include current array paths. Avoid casting arbitrary server keys to `keyof FormValues`; a server key may be unknown or a nested path. Client validation, Laravel errors and transport errors then render through one RHF error state. Handle rejection with try/catch as in the complete edit recipe; do not swallow errors or reset a failed draft.
+
+For TanStack Start/Query, pass an app-owned async function: `onSave={async values => { const saved = await saveOrder(values); await invalidateOrders(); return { ok: true, values: saved }; }}`. If server validation returns a structured result, return `{ok:false, errors, message}` instead. Await the server function/mutateAsync Promise and any cache work required before the form becomes editable. Do not pass a fire-and-forget `mutate` callback. A router/framework adapter does not replace RHF's frontend state ownership.
+
+## Overlay create and edit
+
+The complete [customer drawer](../examples/rhf-overlay-form.tsx) uses ActionDrawer and useOverlayVisibility from `features/overlays`. ActionDialog uses the same formId/loading contract for shorter forms. Opening explicitly calls `reset(recordSnapshot)` (or complete empty defaults); onSubmit owns validation and persistence. The overlay footer's `formId` calls requestSubmit on that actual form. Do not combine it with onConfirm/onAsyncConfirm, which would introduce a second submit path.
+
+Pass `loading={isSubmitting}` so confirm/cancel/close/Escape/outside dismissal follow the pending lock. A failed request shows ErrorSummary and field errors while the drawer stays open with its values. Success resets to the returned record, publishes it through onSaved, and hides the controlled overlay. Cancelling without saving leaves the committed record unchanged; reopening begins a new snapshot. If a product requires drafts across dismissal, store drafts outside the overlay and make that policy explicit rather than resetting on open.
+
+## Verify the real workflow
+
+Run the bundled composition checker and the app's type/lint/test scripts. Then execute required-field errors, field focus, typed edits, arrays/reorder/removal, computed totals, duplicate-submit protection, server errors, retry with retained draft, accepted reset and discard. Open the actual date/select/tag surfaces and drawer; check keyboard/dismissal/focus return and light/dark at narrow/wide widths. Static typechecks prove the bindings and exports, not an application's server behavior.

package/docs/consumer-skill/references/screen-archetypes.md

@@ -0,0 +1,34 @@
+# Screen archetypes
+
+Choose by the user's job, then inspect the exact declaration with the [finder](discovery.md).
+The [complete shipped blueprint index](../../../templates/README.md) includes
+the application shell and every domain example. These are source assets at the
+installed package's `templates/`; complete skill copying places them under the
+shared skill's `templates/` and rebases the links below.
+
+Start with [screen decisions](screen-decisions.md). Archetypes establish route responsibilities and supported seams. Inspect the
+actual records before choosing their content regions. A detail page can combine
+existing blocks with app-owned domain components and semantic JSX; comparisons,
+allocations, dependencies and exceptions may need their own information
+structure. Use [data-led composition](custom-composition.md#shape-the-subject-from-the-data)
+to choose that structure. A dashboard does not require a metric-card row, and
+a simple facts subject does not require a custom component.
+
+| Screen | Main owner and regions | Starting blueprint | Application-owned state |
+| --- | --- | --- | --- |
+| Index / directory | Page header/context → DataView, or FilterProvider → DataTable topbarContent={FilterLayout}; default lg, explicit xl/full for wide comparisons | [Scoped directory](../examples/scoped-directory.tsx), [index table](../examples/index-table.tsx) | URL/query, facets, paging, selection, bulk commands, loading/empty/error/retry |
+| Detail workspace | Page narrow for simple detail; page identity and task subjects, optional aside for secondary context (xl); choose continuous/flat or framed subjects deliberately | [Orders](../../../templates/orders-template.tsx), [customers](../../../templates/customers-template.tsx), [record detail](../examples/detail.tsx) | Record snapshot, section/tab, permitted commands, overlay drafts, accepted server results |
+| Settings / edit | `Page narrow render={<form ... />}` → FormSection → ControlledFormField → FormActionsBar; with support use Page aside or explicit maxWidth="xl" + TwoColumnLayout | [RHF edit page](../examples/rhf-edit-page.tsx), [RHF drawer](../examples/rhf-overlay-form.tsx) | RHF values, rules/schema, arrays, computed totals, transport/errors, saved baseline |
+| Order / fulfillment detail | Page header owns order identity and commands; Alert for standing notices; FulfillmentGroup per status/location; ShipmentTracking; OrderCustomer, OrderSummary and OrderTransactions as aside cards | [Order and invoice map](commerce-composition.md), [order recipe](../examples/commerce-lines.tsx) | Order snapshot, fulfillment/refund commands, payment state, accepted results |
+| Invoice / receivable detail | Page header with collection commands; one document Card → InvoiceHeader + InvoiceLineItems surface="flat"; settlement ledger, payment history and customer as separate subjects | [Order and invoice map](commerce-composition.md), [invoice recipe](../examples/commerce-lines.tsx) | Invoice values, tax policy, balance, payments and reminder/credit workflows |
+| Product editor | Page → product identity/media/shared details → product option definitions → generated variant list/matrix and selected editing workflow; publishing context remains distinct | [Products](../../../templates/products-template.tsx) | Product snapshot, stable option/value IDs, combination identities, per-variant drafts, publishing validation and persistence |
+| User access / permissions | Page → profile and role context → editable permission groups → save/discard feedback | [User permissions](../../../templates/user-permissions-template.tsx) | Role presets, permission draft, permitted commands, accepted-save/discard baseline and server enforcement |
+| Analytics overview | Page period control → numeric MetricBar/MetricGrid → ChartCard with Recharts series and comparison Cards → operations/usage regions | [Operations analytics](../../../templates/analytics-operations-template.tsx), [analytics states](../examples/analytics.tsx) | Period/query, metric formatting, accepted series, independent loading/error/retry states |
+
+Page uses explicit maxWidth first, then narrow md (48rem), aside xl (80rem), otherwise lg (64rem). Settings navigation uses Page → SettingsShell → FormSection. Page owns its h1, gutters and direct-child rhythm; TwoColumnLayout owns the column split and peer-region rhythm. Stack/Grid own nested sibling gaps. Card owns framing and aligned header/body/footer insets. Authentication uses [AuthShell](authentication.md), and content sites use [Container/Section](../examples/website.tsx).
+
+Keep FilterLayout inside DataTable topbarContent with variant="compact" and showClearFilters, under FilterProvider; DataView is the complete alternative. Table owns its frame/topbar/header band and sits directly in the layout. A deliberate Card host uses padding="none" and a flat table. Fixed scope belongs in page context or tabs, independently of removable criteria.
+
+Headers carry one primary command and ordered secondary commands; below 40rem of header width all commands share one More actions trigger. Page header slots beforeTitle/titleSuffix/afterDescription/actions accept content or callbacks with {renderLink, defaultContent}. Compose status and facts with Badge/MetadataList; wrap or return actions defaultContent to retain the command row. Compatible direct actions add non-command controls. Put destructive commands behind ConfirmDialog. Longer create/edit work belongs in ActionDrawer; a short focused form uses ActionDialog. Preserve a snapshot until save succeeds. Templates are copyable application sources, not package component entrypoints.
+
+Read only the relevant detail: [composition ownership](composition.md), [workflow states](workflows.md), [RHF transport and bindings](rhf-workflows.md), or [analytics contracts](analytics.md). The [review checklist](review.md) separates static checks from opened-surface and interaction evidence.

package/docs/consumer-skill/references/screen-decisions.md

@@ -0,0 +1,126 @@
+# Decide the screen before selecting components
+
+Use for a new business screen or a substantial composition repair. The public
+API tells you what is supported; it does not decide what deserves prominence.
+Settle the following in a few working notes before JSX. This is a design step,
+not an approval gate or a required document for a small edit.
+
+## Task, subject and priority
+
+Name the user's job and the object being managed. Inspect a representative
+record and an exception. Distinguish the product's structure from one selected
+instance, current operational state from historical evidence, and editable
+configuration from read-only facts.
+
+Discover the task-specific owners and their supported parts before drawing those
+regions. Use the [capability comparison](custom-composition.md#compare-capabilities-before-constructing-the-subject),
+then let app markup express the relationships those owners must cooperate in.
+Token-backed custom structure complements existing behavior; it does not replace
+the discovery of a professionally supported subject/workflow.
+
+Put the information needed for the immediate decision first in reading and DOM
+order. Then show the supporting detail, then less frequent history or technical
+evidence. A desktop aside must not bury the current balance or blocking exception
+below several screens of history on mobile. A record can contain all required
+fields and still have the wrong hierarchy.
+
+For a catalogue product, product identity/media and shared details establish the
+subject. Product-level option groups and values explain the generated variant
+combinations; the variant list/matrix compares SKU, price, availability and
+state. Editing one variant is a subordinate selection/workflow. A large selected
+variant summary before the product's option structure instead resembles a buyer
+picker. A storefront picker, a catalogue editor and an inventory workspace have
+different priorities even when they use the same data.
+
+An admin product workspace commonly needs distinct details, media-management
+and variant work areas. Do not put a gallery beside prose simply because both
+are available, or reproduce a storefront hero inside an operational editor.
+Choose each region's role and placement first; selecting a dedicated component
+does not decide that structure for you.
+
+For a sold order line, purchased identity, selected options/SKU, quantity and
+accepted amounts form one subject. Put a shortage, reservation or return beside
+the affected goods. Do not repeat every zero-valued lifecycle counter as a
+separate labeled stack. For an invoice, distinguish its issued legal document
+from today's settlement/collection task; both can be present without giving
+every source record equal prominence. See [domain coverage](custom-composition.md).
+
+## Actions and navigation
+
+Assign each command a scope (page, collection, selection, subject or row), then
+consider frequency, importance, eligibility and consequence. Make the ordinary
+next action easy to find. Less frequent alternatives belong in the same scope's
+overflow menu when their visible buttons would compete with the subject. A
+refund on an ordinary sold line is commonly a secondary contextual action; a
+returns-processing workspace can legitimately make it primary. A single action
+does not automatically need a menu, and several actions do not all need buttons.
+
+Use Page's command API for page commands and its responsive overflow behavior.
+Use the public Menu/rowActions owner for item commands; give an icon-only trigger
+an accessible name that identifies the object. Confirmation belongs to the
+consequential action, not to opening the menu. Never hide an essential action
+solely behind pointer hover.
+
+Optional navigation is a decision too. Do not add a back button just because
+Page accepts backHref. Use it for an actual return journey with a known
+destination and preserved list/draft context. A persistent navigation area or
+breadcrumb may already supply orientation. Respect the requested navigation
+pattern; do not combine several competing return mechanisms by default.
+
+## Grouping, surfaces and alignment
+
+Group facts that users need to read together. Choose a Card when a region is an
+independent subject, a distinct object or a useful bounded work area. Continuous
+sections of one subject can remain flat inside a shared surface. Neither every
+heading nor every object in JSON requires a Card. Existing table/workflow owners
+can already own their boundary; inspect before adding another frame.
+
+Decide the inset owner separately from the surface's paint. Card
+surface="flat" removes chrome and inherits its host; it retains the same default
+md insets. Changing paint alone must not move a peer's content edge. Use
+padding="none" when an existing ancestor already owns that inset, or when a
+deliberately flush region is required—not as a synonym for transparency.
+Compare heading, body and action start edges across peer regions. An unpadded
+main heading next to an inset card heading is not aligned merely because their
+outer grid cells align. Document-like rows and financial totals can use different
+roles, but their intended label/value axes should remain clear.
+
+For continuous sections of one subject, one padded host with unpadded internal
+sections usually supplies the right rhythm. Stacking several padded flat Cards
+adds both their block insets to the peer gap even though no painted boundary
+explains that extra room. Keep shared inline alignment without accumulating
+three inset owners along the vertical axis.
+
+Assign page gutters to Page, surface insets to Card, peer gaps to Stack/Grid,
+and specialized tracks to app-owned markup. Keep title/description copy close;
+separate subjects with a larger gap. Fix the wrong owner before changing global
+spacing or density. Use [token-backed domain structures](domain-structures.md)
+when the standard layouts cannot express the data relationship directly.
+
+## Prove the decision with the result
+
+Build one representative subject before repeating it throughout the screen.
+Inspect it at the actual narrow and wide parent widths: can the user identify
+the object, understand its current state and find the next appropriate action?
+Check the opened menu/editor and accepted/error state. Remove duplication and
+low-value explanation rather than shrinking every text role to fit more data.
+Test a second record whose structure or eligibility differs.
+
+Type checks establish API compatibility. Source checkers establish their named
+rules. Neither establishes a purposeful hierarchy, appropriate commands or a
+professional surface composition. Treat a correct but confusing result as
+unfinished; revise the composition, then record appearance and interaction proof
+separately in [review](review.md).
+
+## External context
+
+These references explain useful distinctions; Themelia's APIs/tokens and the
+actual product requirements remain authoritative:
+
+- [Shopify's product model](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections)
+  separates product, options and purchasable variant combinations.
+- [Carbon disclosures](https://www.carbondesignsystem.com/building-blocks/core/patterns/disclosures)
+  distinguishes a visible primary action from related disclosed alternatives.
+- [GOV.UK back links](https://design-system.service.gov.uk/components/back-link/)
+  grounds return navigation in an actual multi-page journey. Its transaction
+  conventions are not a universal admin-shell prescription.

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

@@ -4,7 +4,7 @@ The [design contract](design-contract.md) records which geometry changes togethe
 and which variant choices remain independent. Retheme shared responsibilities;
 avoid overriding individual components to imitate another density or inset.
 
-Use shadcn semantic surfaces/foregrounds: background, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, charts and sidebar. Central success/info/warning foreground pairs express states; never overload primary or statuses as decoration. `--input` is the one resting control boundary: fields, select and date triggers, checkboxes, radios, switch tracks and outline buttons all draw it, so adjoining controls read as one family. It provides at least 3:1 contrast on the declared background, card, popover, muted, accent and secondary surfaces in both modes. Focus and invalid edges retain their separate 3:1 contract. `--border` is for quieter dividers and surface edges. When rebranding, check resting controls as well as focused controls, including the outside edge of fields with their own fill.
+Use shadcn semantic surfaces/foregrounds: background, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, charts and sidebar. Central success/info/warning foreground pairs express states; never overload primary or statuses as decoration. `--input` is the shared resting control boundary: fields, select and date triggers, checkboxes, radios, switch tracks and outline buttons draw it. Its defaults follow shadcn neutral: `oklch(0.922 0 0)` in light mode and `oklch(1 0 0 / 15%)` in dark mode. `--border` remains the surface/divider role, and `--ring` owns the stronger focus indicator. No extra border variable or component opacity is needed. Resting borders have no blanket 3:1 requirement in this palette; focus retains its separate tested 3:1 contract. When rebranding, review resting, focused and invalid states on the actual surfaces; an application requiring stronger boundaries can override the existing `--input` role.
 
 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.
 
@@ -15,29 +15,21 @@ surface, use Text/Value `type="inherit"` and Label `className="text-inherit"`;
 standalone typography keeps its documented defaults. Keep secondary, link, status
 and inverse roles explicit, and use a secondary text role instead of fading text
 with opacity. Component disabled props own dimming; an extra faded wrapper can
-multiply it. Brand colors alone do not guarantee input/focus contrast: retain the
-central `--input`/`--ring` roles or verify their replacements on every host surface.
+multiply it. Brand colors should preserve the shared resting `--input` palette
+and `--ring` focus role; review deliberate replacements on every host surface.
 
-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.
+The default `--radius` is 0.75rem (12px). One public root drives two corners;
+component owners apply them, 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.
+| `rounded-radius` | The default: inputs, buttons, select/facet triggers, badges, collection/navigation rows and nested bodies | 12px (`--radius`) |
+| `rounded-surface` | Cards, popup/command shells, dialogs and other outer surfaces | 16px (4/3 × `--radius`) |
+| `rounded-radius-xs` / `-sm` / `-md` | Small mechanics only: checkboxes, kbd, tooltips, inline marks, skeleton bars | 0.4× / 0.6× / 0.8× |
+
+Changing `--radius` changes every corner together. Density, spacing scale and
+surface padding do not change it. Circular avatars/dots and joined-edge resets
+retain their explicit shape mechanics.
 
 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
@@ -50,8 +42,8 @@ replacing individual components' owned corners.
   --radius: 0.75rem;
   --height-action: 2.5rem;
   --height-control: 2.5rem;
-  --surface-x: 1.25rem;
-  --surface-y: 1.25rem;
+  --surface-x: 1.5rem;
+  --surface-y: 1.5rem;
 }
 ```
 
@@ -60,14 +52,13 @@ Action and editable-control heights are separate roles; keep roots equal for adj
 Control heights are nominal floors when custom typography needs more room.
 Native fields, Select and InputGroup frames fit their editable line plus the
 border, and cap vertical padding to the space remaining in the nominal height.
-The default 32/36/40px sizes and radius roles stay unchanged. Text actions grow
+The default 28/32/36px sizes (2rem roots, steps in eighths) and radius roles stay unchanged. Text actions grow
 under their intentionally tighter leading, so independently enlarged type can
 produce different fitted heights even with equal action/control roots. Check
 type size, leading and height roots together when exact custom pairing matters.
 
-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,
+Both surface roots default to 1.5rem. At a 16px root font and space-scale 1,
+the xs/sm/md/lg surface tiers are 12/16/24/32px. Page's default large gutters inherit that same recipe. Row insets,
 control heights and copy gaps keep their independent roots.
 
 | Shared geometry | Root / derivation |
@@ -76,9 +67,11 @@ control heights and copy gaps keep their independent roots.
 | Native field text inset | `--control-x` times space-scale; icons/add-ons use shared derived clearance |
 | Collection inline inset | `--row-x` times space-scale |
 | Collection block inset | `--row-y` times density-scale; compact/comfortable use 0.75/1.25 multipliers |
-| Default / compact surfaces | `--surface-x` / `--surface-y`, times space-scale; compact uses half |
+| Surface tiers | `--surface-x` / `--surface-y`, times space-scale; xs/sm/md/lg use 1/2, 2/3, 1 and 4/3 |
 | Menu header/footer inline inset | Half surface-x plus row-x, then space-scale; no additional public token |
 
+Rich display popovers use the surface roots (24px by default); compact menu/list shells use the md spacing role (8px), scaled once by --space-scale. Row inline padding and density stay independent.
+
 Use discrete inset, density and size props for the component responsibility described in [composition](composition.md). CSS scales are independent continuous theme settings. Primary row text does not shrink to xs merely because a density is compact. Public Input and Command search retain normal desktop editable text; coarse-pointer devices use text-base at mobile and tablet widths. Typography components remain margin-free.
 
 The default primary is near-black so success and other status colors never compete
@@ -152,6 +145,11 @@ heavier border.
 
 ## Extend without drift
 
+For Tailwind placement and drawing in app-owned composites, read
+[app-owned composites](custom-composition.md#token-backed-placement-and-drawing).
+That guide separates new content geometry from the public component anatomy
+that still owns its surface, interaction and typography.
+
 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.
 
 Use public structures/utilities for custom composition. Missing API seams should be additive props/slots rather than copies of private code. Review light/dark foregrounds and opened portals. CSS owns theming, UIProvider stable display defaults, callbacks app state.

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

@@ -1,6 +1,6 @@
 {
   "package": "themelia-react-ui",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "structural": [
     {
       "name": "--space-scale",
@@ -24,12 +24,12 @@
     },
     {
       "name": "--height-action",
-      "default": "2.25rem",
+      "default": "2rem",
       "purpose": "Default button and action-trigger height."
     },
     {
       "name": "--height-control",
-      "default": "2.25rem",
+      "default": "2rem",
       "purpose": "Default input, select, and field-control height."
     },
     {
@@ -49,12 +49,12 @@
     },
     {
       "name": "--surface-x",
-      "default": "1.25rem",
+      "default": "1.5rem",
       "purpose": "Default inline inset for cards and multi-content surfaces."
     },
     {
       "name": "--surface-y",
-      "default": "1.25rem",
+      "default": "1.5rem",
       "purpose": "Default block inset for cards and multi-content surfaces."
     },
     {
@@ -69,7 +69,7 @@
     },
     {
       "name": "--shell-header-height",
-      "default": "4.5rem",
+      "default": "4rem",
       "purpose": "Minimum height of the application header shell."
     },
     {
@@ -121,10 +121,10 @@
   "radius": {
     "name": "--radius",
     "default": "0.75rem",
-    "purpose": "Shared 12px outer corners; inner control/row corners derive from this root and stay rectangular.",
+    "purpose": "Default 12px corner for controls, badges and rows; outer shells use 4/3 of it.",
     "defaultUtility": "rounded-radius",
-    "innerUtility": "rounded-inner",
-    "innerFormula": "min(calc(var(--radius) * 0.75), calc(min(var(--height-action), var(--height-control)) * var(--density-scale) / 4))"
+    "surfaceUtility": "rounded-surface",
+    "surfaceFormula": "calc(var(--radius) * 4 / 3)"
   },
   "advanced": [
     "--font-heading",
@@ -465,7 +465,7 @@
       "rounded-radius-xs",
       "rounded-radius-sm",
       "rounded-radius-md",
-      "rounded-radius",
+      "rounded-surface",
       "rounded-radius-lg",
       "rounded-radius-xl",
       "h-action-xs",
@@ -532,7 +532,7 @@
       "size-upload-avatar-small",
       "size-upload-avatar",
       "size-upload-avatar-large",
-      "rounded-inner"
+      "rounded-radius"
     ],
     "layout": [
       "h-shell-header",
@@ -561,30 +561,39 @@
       "py-row-y",
       "py-row-y-lg",
       "p-surface-xs",
+      "p-surface-sm",
       "p-surface",
       "p-surface-lg",
       "px-surface-xs",
+      "px-surface-sm",
       "px-surface",
       "px-surface-lg",
       "py-surface-xs",
+      "py-surface-sm",
       "py-surface",
       "py-surface-lg",
       "pt-surface-xs",
+      "pt-surface-sm",
       "pt-surface",
       "pt-surface-lg",
       "pb-surface-xs",
+      "pb-surface-sm",
       "pb-surface",
       "pb-surface-lg",
       "ps-surface-xs",
+      "ps-surface-sm",
       "ps-surface",
       "ps-surface-lg",
       "pe-surface-xs",
+      "pe-surface-sm",
       "pe-surface",
       "pe-surface-lg",
       "pl-surface-xs",
+      "pl-surface-sm",
       "pl-surface",
       "pl-surface-lg",
       "pr-surface-xs",
+      "pr-surface-sm",
       "pr-surface",
       "pr-surface-lg"
     ]