themelia-react-ui 2.0.4 → 2.0.6

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

@@ -5,27 +5,54 @@ 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.
 
 These criteria allow different product layouts. Do not impose a universal card
 count, row-line limit or one-column form rule. Emphasis is the exception: keep
-one solid primary command per page or surface, so the next action stays obvious.
+one leading primary command per task/surface, so the next action stays obvious.
+Independent forms can each own a primary submit. Fix a warning by reviewing its
+scope and owner; a DOM-lookup submit handler or flattening every FormSection
+does not establish a better composition.
 
 ## Done means
 
 UI work is complete only with three separate proofs: source/API checks, inspected
-rendered appearance and executed interactions. The source checker below must
+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
@@ -63,7 +90,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
@@ -80,12 +107,49 @@ 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` follows tables through passive wrappers and known
+slots in padded Card/FormSection/explicit ChartCard surfaces. It also warns on
+tables in card/chart footers: place substantial tables in a body or peer layout
+region, or deliberately use Card padding="none" and a flat table.
+`form-actions-bar-placement` reviews a FormActionsBar under a padded surface or
+in a footer that already owns geometry; put action nodes directly in the footer
+or use an edge-to-edge bar in a zero-padding host. Both remain warnings because
+custom hosts need contextual review.
+`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. On mixed/tabbed
+routes, constrain only a form panel with Container maxWidth="md" gutter="none";
+`dynamic-page-measure` warns about expressions that can resize the route header
+along with the body. Deliberate responsive sizing remains valid. 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.
-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
+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 in the same task scope warns,
+counting `header.primaryAction`, solid Button tone="primary", and
+SubmitStateButton's default primary. Native forms (including a public owner's
+native form `render`) and overlays own separate command scopes; exclusive
+conditional branches use their maximum count. Local submits stay with their
+form. `remote-header-form-submit` reviews header handlers that call
+document.getElementById and requestSubmit, including same-file callback values;
+a deliberate single full-page editor can keep its header submit with native
+validation and appropriate form association.
+
+`heavy-cell-disclosure` reviews Accordion, SmartAccordion, DataTable and CodeBlock
+inside statically visible DataTable `columns.cell` renderers, separately from
+column headers and portaled record details. Prefer a summary plus rowActions
+opening an overlay or detail route; intentional accessible inline disclosure is
+valid. `single-option-choice-group` suggests boolean controls for one static
+choice, without banning two-option sets or filtered real choice domains.
+
+Raw palette classes such as
 `bg-blue-500`, `text-gray-600` or `border-white` warn on any element; use a
 semantic surface/foreground pair or a status tone. A Card title icon and an icon on
 more than one MetadataList fact warn as decoration; keep a glyph only when it
@@ -96,7 +160,9 @@ native button passed as a package owner's `render`, such as an Item row
 rendered as a button, is that owner's root and does not warn.
 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.
+compact MetricGrid, flat TaskCard, default ChartCard and Receipt do not establish
+a frame. FormSection has a Card by default; ChartCard establishes one only with
+an explicit non-flat surface. Unknown surface values/spreads are not proof of 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.
@@ -111,9 +177,20 @@ 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.
+heading copy and same-file static classes/styles/props/JSX slot values. Paired
+and self-closing elements retain their slot owner; opaque app components and
+known portals form separate regions. Inline cell renderers are inspected when
+their JSX is available, without executing application code. Dynamic geometry,
+classes and spread values are disclosed as unresolved where inspected;
+cross-file wrappers, external CSS and runtime composition require review. Do not
+treat an empty report as proof of complete compliance or taste. Test source
+rules through analyzer findings, and UI behavior through executed outcomes;
+regex assertions over app JSX cannot establish either visual quality or callbacks.
+Local helpers invoked to produce JSX (for example `footerSlot={renderFooter()}`)
+are not evaluated. Dynamically constructed whole header objects are disclosed
+as unresolved; review their action scopes separately. Native ReactDOM
+createPortal calls retain their lexical binding and start a separate rendered
+region, like the supported public overlay owners.
 
 ## Rendered and interaction evidence
 

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

@@ -4,12 +4,40 @@ Use `react-hook-form` for form state in create/edit pages, settings and overlays
 
 ## 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.
 
+Choose each section's frame from its actual parent. Independent FormSections on
+the page can keep their default card surface; flattening a section whose content
+already consists of Cards does not require flattening unrelated sibling forms.
+
+`FormActionsBar` owns a top divider, opaque background and surface inset. Use
+`leading` for status and `trailing` (or `children`) for action nodes. In
+`Card padding="none"`, flat FormSections keep their body inset and the bar sits
+edge-to-edge after them. In an ordinary Card's `footerSlot` or FormSection's
+`footer`, place the buttons directly: the host already owns the footer geometry.
+`SubmitStateButton` defaults to `type="submit"` and primary tone; pass
+`submitting`, `dirty` and `disableWhenPristine` for pending/pristine behavior.
+
+Independent forms own independent submit commands. Keep a lookup beside its
+input and settings saves with their edited fields; page command guidance does
+not require moving these into `Page.header`. For a single full-page editor, a
+deliberate header submit can use native form association (`type="submit"` and
+`form` on a Button in a supported slot). Preserve browser validation and one
+submit lifecycle; routine `document.getElementById(...).requestSubmit()` handlers
+add unnecessary coupling. Tests should execute validation, pending, error/draft
+retention and accepted persistence rather than assert a particular source string.
+
 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.
@@ -33,12 +61,63 @@ Mount an editor with `key={record.id}` when switching records. `defaultValues` e
 | SliderField (public slider name) | scalar `value: number` | `onValueChange(value)`; `inputRef`, `onBlur` |
 | ColorInput | `value: string` | `onValueChange(value)`; input `ref`, `onBlur` |
 
+Set DatePicker's `mode` explicitly when binding its callback. `mode="single"`
+narrows the output to `DateOutput`; range and multiple modes have their own
+value/output shapes. The runtime's single-mode default does not narrow the
+unified callback's contextual TypeScript type.
+
+Bind an empty controlled date field with `value={field.value ?? undefined}`.
+An external reset to that empty value clears single, multiple, range and
+month/year selections. Do not also pass `defaultValue` unless restoring that
+fallback is intentional; RHF's `defaultValues` owns the saved form baseline.
+
 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.
 
+Use `FormRichTextEditor` from `themelia-react-ui/features/rich-text-editor`
+inside an RHF `FormProvider`. Pass its field name and wrap it in `FormField`
+with the field's validation message. The binding handles touch, focus,
+invalid and disabled state. Both editor modes use the same field association.
+Native form data includes the committed HTML for enabled, named editors.
+Switch from HTML source to rich text to commit a source draft.
+
+WeightInput, DimensionsInput and CoordinatesInput can bind `field.onChange`
+through `onValueChange` and `field.onBlur` through `onBlur`. Their legacy
+event-shaped callbacks still receive the same value. Native `name` submits
+one numeric string, using `widthxheightxdepth` for dimensions and
+`latitude,longitude` for coordinates. The React callback retains the
+selected string or object format.
+
+TimePicker accepts the same direct `value` and `onValueChange` binding
+and submits a named 24-hour value in either mode. Bind `field.onBlur`
+to report leaving the complete picker, including its open popover.
+
+### Empty selections
+
+| Owner | Empty value |
+| --- | --- |
+| PillRadioGroup with `allowClear` | `null` |
+| Combobox and AsyncResourceCombobox | `null` |
+| MultiCombobox | An empty array |
+| Select and RoundingModeSelect with `allowClear` | `undefined` |
+| DateTimeInput | `undefined` |
+| TimePicker | A controlled `null` shows an empty time. Editing emits aligned strings. |
+
+Normalize nullable callbacks at the form boundary when the app uses one
+empty value. An explicit `value={undefined}` keeps PillRadioGroup controlled.
+Omit `value` to use its `defaultValue`. A shared clear sentinel would require
+a major release.
+
 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.
 
+FormField honors an explicit `htmlFor` target already declared in descendant JSX,
+including arrays/fragments, without copying its ID or name onto the outer wrapper.
+It does not inspect custom component bodies. If a compound creates its nested
+controls internally, put it inside Stack or a native container and assign the
+target ID and supporting-text attributes to the actual control. Direct controls
+without an ID retain automatic association.
+
 ## 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.

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

@@ -6,17 +6,29 @@ 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 → fixed scope/context → FilterLayout → DataView/DataTable; maxWidth="full" when comparison needs it | [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 title/status/commands/tabs above TwoColumnLayout; subject Cards in main, facts/support in aside | [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 render={<form ... />}` → dirty/error feedback → TwoColumnLayout → FormSection → ControlledFormField → sticky FormActionsBar | [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 |
-| Product editor | Page → product subjects and publishing/support regions → variant editor workflow | [Products](../../../templates/products-template.tsx) | Product snapshot, option/variant drafts, publishing settings, validation and persistence |
+| 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 → comparison/chart 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 |
+| 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).
 
-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; period selects and similar non-command controls use header actions. 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.
+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,6 +4,10 @@ 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.
 
+Set the application's document font and page background/foreground through the
+[host CSS setup](installation.md#set-the-application-canvas). Importing package
+styles defines theme roles without painting the document or resetting app markup.
+
 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.
@@ -18,26 +22,18 @@ with opacity. Component disabled props own dimming; an extra faded wrapper can
 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
@@ -60,7 +56,7 @@ 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.
@@ -74,9 +70,12 @@ control heights and copy gaps keep their independent roots.
 | Actions versus fields | `--height-action` versus `--height-control`; default size uses the root times density-scale |
 | 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 |
+| Item/table row block inset | `--row-y` times density-scale; compact/comfortable use 0.75/1.25 multipliers where supported |
+| Anchored collection block inset | Default/comfortable use 0.75/1 × `--row-y` × density-scale; compact uses the spacing-scaled 2xs step |
 | 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 |
+| Menu header/footer inline inset | Compact bands use the md spacing step; plain header/footer copy adds the xs step. Leading controls and actions stay on the band edge. |
+
+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.
 
@@ -151,6 +150,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.4",
+  "version": "2.0.6",
   "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."
     },
     {
@@ -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",