themelia-react-ui 2.0.4 → 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.
 
@@ -25,7 +47,9 @@ one solid primary command per page or surface, so the next action stays obvious.
 ## 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 +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
@@ -80,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

@@ -4,6 +4,13 @@ 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`.

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

@@ -18,26 +18,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 +52,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.
@@ -78,6 +70,8 @@ control heights and copy gaps keep their independent roots.
 | 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
@@ -151,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.4",
+  "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."
     },
     {
@@ -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",

package/docs/consumer-skill/references/view-craft.md

@@ -0,0 +1,153 @@
+# View craft
+
+Themelia already sets type, colour, spacing and surfaces. Craft is what remains:
+deciding what a view shows, how much emphasis each part gets and how the parts
+are arranged, so the user understands the screen at a glance. Each rule below is
+a decision you can explain and check on the rendered result. Most improvements
+remove something.
+
+Start from the [data brief](data-reading.md#write-the-data-brief). Owner
+selection, surfaces and inset ownership follow
+[screen decisions](screen-decisions.md); this reference does not restate them.
+
+## One focal point
+
+Each view, and each region in it, has one thing the eye reaches first: the
+figure that answers the question, the subject's identity and state, or the queue
+of records that need action. Choose it from the brief. When two things compete,
+demote one: a smaller text role, secondary tone, or a supporting region.
+
+Check it by looking at a reduced screenshot: the focal point is still the
+strongest mass. It sits in the first viewport at both 390 and 1440 wide.
+
+## Spend emphasis on purpose
+
+Emphasis works only by contrast, so it is a budget:
+
+- **Commands.** One solid primary command per page or surface. Other commands
+  are outline or ghost, or sit in the same scope's overflow menu.
+- **Text.** At most three levels in a region: title (`Heading`), body and values
+  (`Text`), supporting copy (`Text` secondary, smaller size). A fourth level
+  signals a hierarchy problem, not a missing style.
+- **Tone.** `success`, `warning`, `destructive` and `info` mark a status that
+  changes what the user does. Kinds, categories and counts stay neutral. When
+  everything is coloured, nothing reads as status.
+- **Size.** One hero figure size per region; peer figures share one size.
+
+Adding emphasis in one place means removing it from another.
+
+## Choose the encoding from the fact
+
+| The fact | Encoding | Owner family (confirm with the finder and inspector) |
+| --- | --- | --- |
+| A figure the user must judge | Figure with its baseline delta; a sparkline when the path matters | `Metric`, `MetricTrendChip`, `MetricSparkline`; `MetricComparison` for current versus previous |
+| Several peer figures for one period | One strip, not a grid of identical cards | `MetricBar`; `MetricGrid` with a quiet variant inside one surface |
+| A series whose shape is the message | Chart with one emphasised series and minimal axes | `ChartCard` with Recharts children |
+| Part of a whole, or use against a limit | Bar with the figure as its label | `Progress`, `UsageCard` |
+| Facts about one record | Label and value list; one inline line for two to four short facts | `MetadataList` (inline or stacked), `InlineStat` |
+| A lifecycle with a current stage | Steps with only the current stage emphasised | `StepsHorizontal`, `Timeline` |
+| Events and history | Newest first, grouped by day | `Timeline`, `features/activities` |
+| Many records compared on shared columns | Table whose columns are what users compare or sort | `DataTable`, `DataView` |
+| Records that differ in shape | List rows: identity, one line of context, state, action | `Item`, `ItemGroup` |
+| A money ledger | Right-aligned amounts, one rule above the grand total | `SummaryPanel` with `AmountRow`, `OrderSummary` |
+| Nothing to show yet | What is missing and the next action | `EmptyState` |
+
+Read [metrics and statistics](analytics.md) for the exact metric owner. A chart
+must answer a question you can write in one sentence; otherwise show the figure.
+Do not chart three values. Prefer a sparkline in a strip to a large chart that
+repeats what the figures already say.
+
+## Spend words carefully
+
+- Label a value only when it is ambiguous. A ledger amount needs "Total"; an
+  order number in a header does not need "Order number".
+- Do not repeat a column header inside its cells or a section title in each row.
+- State a unit once, in the header or the value.
+- A sentence fragment often reads better than three label and value pairs:
+  "2 of 3 shipped · 1 reserved at Plovdiv".
+- Omit zero and not-applicable counters, or collapse them into one "Nothing
+  outstanding" line.
+- Do not explain the interface on the page. A description states scope or
+  as-of time, not instructions.
+
+## Density follows the audience
+
+- **Queues** for operators: compact rows, more records per screen, identity,
+  state and amount; detail on open.
+- **Overviews**: fewer, larger figures with room around them, each answering a
+  question.
+- **Records**: the subject leads; evidence and history follow.
+
+Change global density through the provider and density roots described in
+[theming](theming.md). Do not shrink text roles to fit more data; remove
+low-value content first.
+
+## Rhythm groups content
+
+- Gaps grow outward: within a group, between groups, between sections. Equal
+  gaps everywhere mean nothing groups. Use `Stack` and `Grid` gap roles.
+- Few edges: peer regions share content start edges; numbers right-align on one
+  axis; labels share one axis.
+- Few frames: one `Card` per independent subject. Continuous sections of one
+  subject share one surface and are separated by space, not rules or nested
+  boxes.
+- Narrow widths keep the decision content first in reading order. Only data
+  tables that own horizontal scrolling may scroll sideways.
+
+## Numbers and copy
+
+- Numbers use tabular figures through the value primitives (`Money`, `Number`,
+  `Percent`, `Date`, `RelativeTime`) with one precision per column.
+- Recency reads as relative time with the exact date available; documents show
+  absolute dates.
+- A delta states direction and baseline: "↓ 0.9% vs September".
+- Sentence case everywhere. Buttons are a verb and an object ("Record payment").
+  Empty states say what is missing and what to do. Errors say what happened and
+  how to recover.
+
+## Modern patterns and their owners
+
+- **Overview.** A header with the period control, one figure strip (three to
+  five figures with deltas or sparklines), one chart answering the main
+  question, and a "needs attention" list that links to records. Not a wall of
+  identical cards.
+- **Index.** Search plus the work queues users actually work; rows lead with
+  identity and the deciding column; bulk actions appear with a selection;
+  export states how many rows match.
+- **Record.** The page header carries identity, status badges in `titleSuffix`,
+  one metadata line (date · channel · customer) and the primary command. The
+  main column holds the subject's working content, an aside holds context
+  (customer, payment, notes) and history comes last.
+- **Editing.** `InlineEdit` for one field; `ActionDrawer` for a focused
+  multi-field edit that keeps the record visible; `ActionDialog` for short
+  creation; `ConfirmDialog` for destructive commands.
+- **Progressive disclosure.** `Collapsible` or `Accordion` for evidence and
+  technical detail; overflow menus for rare commands.
+- **Loading.** Owners' loading states and `Skeleton` shaped like the content,
+  not spinners in empty boxes.
+
+Inspect each owner's declaration before using it; a pattern names a direction,
+not a prop list.
+
+## Anti-patterns seen in trials
+
+- A grid of identical metric cards whose figures have no baseline.
+- A facts card that repeats the header's identifier, status and date.
+- Every lifecycle counter on every line, zeros included.
+- Column headers repeated in cells; units on every value.
+- Filler cards added to balance a column's whitespace.
+- Decorative icons on titles, rows or badges; tinted icon tiles.
+- Status tones on kinds or categories; three badges on one row saying related
+  things.
+- A storefront hero image inside an operational editor.
+- A framed box inside a card for sub-content that is not a distinct object.
+- A chart of three values, or a chart whose question cannot be stated.
+- Prose explaining what the screen does.
+
+## When an owner limits the view
+
+When an owner cannot express the hierarchy the data needs, compose its public
+parts or app markup with token-backed utilities
+([domain structures](domain-structures.md)) and report the gap by owner and
+prop. Never override anatomy classes, add colours or add tokens to make a view
+look designed.

package/docs/consumer-skill/references/view-spec.md

@@ -0,0 +1,73 @@
+# View spec
+
+Write this before JSX for a new view or a substantial redesign. Keep it short
+enough to read in a minute; it is a working note, not an approval document. Every
+line should change a later decision. Save it beside the app's other design notes
+so a reviewer can compare the result with the intent.
+
+```md
+# <View name> (<route>)
+
+## Decision
+<who> decides <what>, <how often>. Success: <what they can do faster or with more confidence>.
+
+## Data brief
+<the data brief from data-reading.md>
+
+## Ranked information
+- Must (first viewport at 390 and 1440): …
+- Should (visible without interaction): …
+- Could (behind disclosure, overflow or a detail view): …
+- Omit: … (why: zero, not applicable, duplicated elsewhere, not used for this decision)
+
+## Focal point
+<the one element the eye reaches first, and why>
+
+## Wireframes
+1440:
+┌──────────────────────────────────────────────┐
+│ Title · status          [secondary] [Primary]│
+│ meta · meta · meta                           │
+├──────────────────────────────┬───────────────┤
+│ main subject                 │ context       │
+│ …                            │ …             │
+└──────────────────────────────┴───────────────┘
+
+390:
+┌────────────────────┐
+│ Title · status     │
+│ [Primary]   [⋯]    │
+│ main subject       │
+│ context            │
+└────────────────────┘
+
+## Encodings
+| Fact | Encoding | Why |
+| --- | --- | --- |
+
+## Owners
+| Region | Owner | Exact import | Verified with |
+| --- | --- | --- | --- |
+(found with find-components.mjs and map-composition.mjs; props checked with inspect-component.mjs)
+
+## Commands
+<command: scope, emphasis (primary, secondary, overflow), eligibility and disabled reason>
+
+## States
+Loading: … Empty: … Error and retry: … Accepted: … Long text and narrow parent: …
+
+## Open questions and data gaps
+…
+```
+
+## Notes
+
+- Draw wireframes in text so they survive any editor and diff. Boxes show
+  regions and order, not pixel sizes.
+- The ranked list is where most quality comes from. If "must" has more than
+  five items, the decision is not specific enough yet.
+- Fill "Owners" only after running the finder and inspector. An owner that does
+  not fit is recorded with the reason, and the region becomes app markup over
+  public parts.
+- After building, score the result with the [critique rubric](critique-rubric.md)
+  and note any departure from this spec with its reason.