themelia-react-ui 2.0.4 → 2.0.6

package/docs/consumer-skill/references/custom-composition.md

@@ -0,0 +1,261 @@
+# App-owned composites
+
+Use this when the product's data needs a particular presentation, when the app
+needs a reusable subject, or when several existing owners should cooperate.
+Start from the user's decision and the data relationships, then choose the seam.
+The four skills cooperate: design decides what the view shows and judges the
+rendered result, components verifies APIs, composition assigns owners, and
+tokenization supplies shared visual roles. A new app component does not imply a
+new library component or token.
+
+## Compare capabilities before constructing the subject
+
+Break the screen into task responsibilities and search each one, including its
+domain nouns. Finding Card, Input and Grid does not finish discovery of a product
+editor's options, variant workflow or media gallery. For each substantial region,
+compare the fitting feature/block and its public parts: accepted data, state and
+callbacks, content/render seams, presentation fit, and what remains app-owned.
+A few working notes suffice; no permission gate or large inventory is needed.
+
+Use the existing owner when it fits; extend its supported content/render seam
+when the data needs extra structure. Check a compound part before replacing a
+convenience wrapper. Custom domain JSX remains a first-class choice for a
+comparison, grouping or relationship, but it is not a reason to recreate an
+existing option editor, gallery selection/reordering, menu or focus lifecycle.
+If an owner seems unsuitable, inspect the exact limitation and its callers.
+Do not mistake incorrect controlled-state wiring for missing support.
+
+The [product capability map](product-composition.md) demonstrates this comparison:
+product options and their generated variant rows, editing one variant, a local
+File[] gallery and already-attached asset records are distinct responsibilities.
+Its examples route to actual public APIs rather than a handcrafted photo grid
+or a new option-pill implementation. Other domains need the same task-specific
+discovery, not the same product layout.
+
+## Shape the subject from the data
+
+Inspect real representative records before choosing a template. Notice which
+facts interact, which values reconcile, where there are stages or dependencies,
+and which exceptional states change the next action. Choose an information
+structure that lets the user understand those relationships in place.
+
+| Data and user decision | Useful subject structure |
+| --- | --- |
+| A supplier's contact details and one edit command | An existing facts/contact block or MetadataList; the simple subject needs no invented workflow |
+| Goods split across warehouses, partially allocated stock, payment coverage and a release hold | A release-readiness subject: affected goods and quantities grouped by warehouse, shortages beside those lines, payment/hold consequences beside the release command |
+| Several payments allocated to invoices, a disputed amount and unapplied credit | An account-reconciliation subject: allocation provenance, collectible/disputed/future balances and the calculation connecting them; keep unallocated credit distinct until an allocation rule applies |
+| Agreed invoice lines plus a service-specific exception | Keep InvoiceLineItems for the invoice subject and add an app-owned exception/decision region through the surrounding composition |
+
+These are examples of relationships, not mandatory component shapes. The
+business rules must establish what can ship, what is collectible or which
+action is permitted. Missing valuation, allocation or policy is unknown; do
+not infer it from a total or manufacture a precise decision.
+
+Choose among an existing block, an app-owned subject made from smaller parts,
+or a combination. The match includes meaning, emphasis and relationships as
+well as prop coverage. A block accepting the fields does not establish that
+its arrangement communicates the task well.
+
+An app-owned component can combine Button, Badge, Text, value primitives,
+Stack/Grid and ordinary JSX such as a definition list, grouped list or
+comparison tracks. App-owned domain functions or authoritative server results
+supply calculations and eligibility; the subject presents those results with
+their explanations and related evidence. Its caller can supply
+permissions, callbacks and transport; the public controls retain their
+keyboard, loading, focus and disabled behavior. Use the shared typography,
+spacing, color and surface roles throughout the custom content.
+
+For example, a `ReleaseReadiness` app component can present the unshipped
+quantity, allocated quantity and shortage for each product, then explain which
+hold blocks release. It can reuse a customer block elsewhere and the existing
+line-item table for price reconciliation. A new name around unchanged generic
+cards adds no information structure; the useful change is making the
+relationship and its operational consequence visible.
+
+Extract a domain component when it gives a coherent subject, useful local
+contract or reuse. Local JSX inside a page is also valid. Neither a new file
+nor custom code is required for every region. After composing, check whether
+the user can make the intended decision without mentally joining disconnected
+facts, and whether the same arrangement would still make sense with a
+different record or exception.
+
+## Check domain coverage
+
+A route title and a fact summary do not establish coverage of an entity. Inspect
+the brief, data types, representative records, related entities and existing app
+flows for the parts users actually work with. Separate the parts present in the
+model, those required by the task but missing, and those outside the task.
+
+| Entity | Inspect when relevant | What changes the presentation |
+| --- | --- | --- |
+| Order | Line items, purchased variant/SKU and selected options, quantities, price adjustments/tax, payment records, fulfillment groups, cancellations/refunds | Item identity and options stay with the purchased line; partial fulfillment and refunds stay with affected quantities; totals reconcile separately from operational readiness |
+| Product | Option groups and values, variant combinations, per-variant SKU/price/inventory/availability/media, publishing and product type | Option definitions differ from sellable variants; use a variant comparison/editor when combinations matter, with shared defaults and exceptions made explicit |
+| Invoice/account | Line items, due dates, payments and allocations, credits/disputes, remaining balance and collection history | Trace the remaining collectible amount and its provenance instead of showing disconnected totals or treating payment state as the complete history |
+
+Adapt this inspection to the product: digital goods, services, subscriptions and
+simple products have different parts. Do not add warehouses, variants or a refund
+workflow just because another product has them. For relevant missing data, state
+the contract or coverage gap rather than presenting an absent region as complete.
+Inspect existing public domain features and templates: the
+[products template](../../../templates/products-template.tsx) demonstrates
+ProductVariantsManager, ProductVariantEditor and ProductVariantDetails from
+features/products, including option groups and variant-level fields. A feature's
+existence is separate from whether this app actually integrates it.
+
+For a requested prototype, use coherent, explicitly mock examples that exercise
+its agreed domain depth: a simple record and representative variants, partial
+states or exceptions. Keep related IDs, selected options, quantities and money
+consistent. Preserve supplied authoritative fixtures; expand an evaluation's
+dataset as an explicit new round so original results remain reproducible.
+For an existing app, inspect its real contracts before adding domain assumptions.
+Report which regions and behaviors were delivered and which remain outside the
+scope or unverified. A rendered generic summary is not evidence of options,
+variant editing, line-level fulfillment or other unimplemented behavior.
+
+## Choose owners before JSX
+
+| Layer | Owns | Does not imply |
+| --- | --- | --- |
+| Typography | Text/Heading/Label roles; semantic tag and visual size are separate | Every nested label should become a large heading |
+| Primitives | Formatted Money, Date, Number, contact and missing values | Raw unstyled interaction primitives |
+| Base | Accessible controls, disclosure, collection, surface and passive structures | A headless kit whose states need restyling |
+| Layout | App chrome, Page identity/gutters, scrolling and responsive regions | Another Card around every route or another shell inside its children |
+| Blocks | Reusable subject presentation with supported local interactions | A complete transport workflow or an implicit frame |
+| Features | Coordinated business workflow, editing/selection/async lifecycle | Exclusive ownership of all interaction in the package |
+
+Stack/Grid/AdaptiveGrid live in base/structure and browse under Foundations.
+Layout sidebar owns application navigation; base/sidebar exposes its lower-level
+anatomy. Prefer AppSidebar for routine grouped/workspace navigation and inspect
+its render slots before reconstructing that behavior. A formatted value, a row
+of record facts and a sidebar are different responsibilities even if all appear
+inside one business panel.
+
+Search each responsibility. A fitting feature can own the workflow; a block can
+own its subject; a base component can own local behavior. Use compound parts when
+the convenience wrapper's bounded shape cannot express the requirement. Combine
+those owners into app content after inspecting the relevant API seams.
+The search term is a task responsibility, not necessarily a package layer.
+
+Before replacing an existing control, disclosure or workflow implementation,
+identify the behavior it cannot express and verify that limit. Composing a
+domain's content from smaller public parts does not require an API gap; its
+data relationships can justify the shape. For an unfamiliar interactive
+composition, retain a brief source note: selected owner/import,
+needed prop or slot, and the behavior that still belongs to the app. No lengthy
+report is needed for routine known controls.
+
+## Disclosure sections
+
+For labeled expandable sections, inspect Accordion and its compound parts before
+choosing Card + Collapsible. Custom badges or retained fields are requirements to
+check, not evidence that Accordion cannot work.
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs "expandable form sections"
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs Accordion --import themelia-react-ui/base/accordion --prop multiple
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs AccordionContent --import themelia-react-ui/base/accordion --prop keepMounted
+```
+
+The [editable sections recipe](../examples/editable-sections.tsx) demonstrates
+multiple open panels, a validation badge inside rich trigger content and
+keepMounted on each content panel. SmartAccordion supports badge nodes but does
+not expose keepMounted. Use compound parts for that verified requirement.
+Collapsible remains appropriate for one custom disclosure; independently framed
+objects can legitimately use Card. The app owns form values, validation,
+submission and opening an invalid section before focusing its field.
+
+Keep the panel title at the subject heading role. A disclosure trigger owns its
+smaller medium label; custom trigger JSX should inherit that scale rather than
+introducing Card title typography. Use Text's size/type inheritance and medium
+weight for a rich label. Include a text separator between label and badge
+(`{' '}` or an explicitly spaced accessible name); a CSS gap alone can produce
+the accessible name "Business details2 errors". Do not place another button/link inside that trigger.
+Custom content is a real styling seam: a Text child with its own weight can
+override the trigger's inherited type even when the outer component is correct.
+
+Preserving a React value alone does not establish mounted DOM. Verify node
+identity and draft retention after closing/reopening, multiple expansion,
+keyboard operation, hidden-field focus, validation badges and submission. The
+recipe does not implement a validation library or persistence.
+
+## Token-backed placement and drawing
+
+The [assessment comparison recipe](../examples/custom-composition.tsx) combines a
+block's label/value role, Money primitives and wrapping Stack actions. It adds
+no Card, heading, inset or control skin; the host owns those. Its Tailwind grid
+chooses exactly two comparison tracks at the local container breakpoint. That
+breakpoint is product geometry. Prefer AdaptiveGrid when automatic equal tracks
+fit; ordinary viewport Grid props are not container queries.
+
+| Need | Use |
+| --- | --- |
+| Peer groups, actions, equal available-width tracks | Stack/Grid/AdaptiveGrid props |
+| A subject's frame/title/body/footer | Card or the selected block's documented surface |
+| App-specific tracks, container queries, alignment, min-width and overflow | Tailwind on the app-owned wrapper |
+| A shared gap/inset in custom markup | Verified gap-space-*, row or surface utility for that responsibility |
+| Text role, formatted value, control or focus behavior | Public typography, primitive or interactive owner |
+| Related components should change together | Supported CSS roots at root/ThemeScope |
+
+Token-backed does not mean appropriate everywhere: gap-space-xl can be correct
+between fields yet padding on AccordionContent or a menu can duplicate its
+owner's inset. No second local radius, focus, hover or disabled recipe is needed
+around an existing control. Missing interaction behavior requires an accessible
+owner or a verified additive seam, not a div styled to resemble a control.
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-tokens.mjs gap-space-xl
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-tokens.mjs --space-scale
+```
+
+Inspect exact utility spelling and overrideRoot. Derived utilities can be used
+as classes; their CSS aliases are not settings to override or read inside a
+scoped calc. A genuinely app-owned formula uses canonical roots and scales
+exactly once. Semantic colors pair surface/foreground (card/card-foreground,
+sidebar/sidebar-foreground); status uses Badge/Alert tones. The lookup does not
+index semantic color values: follow its theme stylesheet/reference reads.
+
+Shipped component CSS and app-authored utility compilation are different. Follow
+[the Tailwind setup](theming.md) before adding classes: a utility in an app's
+source must be generated by its Tailwind build. Package cn supports the shipped
+vocabulary; app-only aliases need the app's merge configuration. Use supported
+public slots/className rather than private imports, DOM descendants or copied
+component recipes.
+
+## Commerce lines and financial summaries
+
+Match the line's meaning before choosing its presentation. `OrderLineItem` from
+`themelia-react-ui/blocks/commerce` keeps a sold product's selected options
+(`variantTitle`), `sku`, `properties`, unit price, quantity and passed line total
+together. Compose `SummaryPanel` with `AmountRow` beneath the goods when the
+subject also needs shipping, tax or a grand total. `AmountRow` accepts an already
+formatted `amount`; `total` sets emphasis and `rollup` draws the rule above the
+financial grand total. The app owns calculations and the surrounding Card.
+
+`InvoiceLineItems` from that same public import fits an invoice's description,
+quantity, unit-price and line-total grid. Its concise default adapts to narrow
+containers and can compute a subtotal/tax/total footer from the supplied line
+totals and tax ratio. Pass `footerRows` for authoritative custom amounts. Typed
+`columns` replace the default grid and narrow layout; each `width` is a CSS grid
+track value, such as `minmax(0, 1fr)`, and each `cell` owns its custom content.
+
+The [commerce lines recipe](../examples/commerce-lines.tsx) shows both choices:
+`SoldProductWithSummary` keeps purchased identity and financial rows together;
+`CustomServiceInvoice` uses two columns with quantity × unit price below the
+service description. It uses public Text/Stack and Number/Money primitives
+instead of styling InvoiceLineItems descendants. Its custom footer gives normal
+Money values `weight="regular"` and the financial total `weight="bold"`.
+`emphasis="total"` controls the footer label, plain-text value and top spacing;
+a React-node value retains its own typography. Select the seam that fits the
+record, then inspect representative narrow/wide output before changing shared
+defaults or imposing the same arrangement on every invoice or order.
+
+## Validate the chosen seam
+
+Check the exact public types and existing source checker, then verify the app.
+Inspect narrow/wide parent widths, both themes, enlarged type and independent
+spacing/density settings. Open a real menu or picker inside the scoped theme;
+a themed trigger alone cannot establish portal inheritance. Exercise local
+state, dismissal/focus, validation and asynchronous paths that the chosen
+composition uses. Keep source, appearance and interaction evidence separate;
+an advisory mapper result or a syntactically valid class list is not visual
+acceptance.

package/docs/consumer-skill/references/data-reading.md

@@ -0,0 +1,79 @@
+# Read the data before the layout
+
+Use before designing or redesigning a view. A layout chosen before the records
+are read turns every field into an equally weighted box. Read four records
+before any JSX: a typical one, the largest, an exception and an empty one. Read
+records, not only the schema: a schema lists every field, while records show
+which few vary, which repeat and which change what the user does.
+
+## What to read
+
+| Read | Ask | It decides |
+| --- | --- | --- |
+| Subject and cardinality | What is the subject? How many children does a typical and a large one have: one line or forty, three variants or sixty? | List, table or grid; whether children need search, paging or a summary line |
+| Ranges and outliers | What are the minimum, typical and maximum of each number? Which records sit far from typical? | Format, column width, default sort and whether an outlier earns emphasis |
+| State frequency | Which states occur, how often, and which one needs action? | Which states take a tone, which collapse into "nothing outstanding", whether zero counters appear at all |
+| Time | Is it a series (values at intervals) or events (things that happened)? | Series become a trend with a stated period and baseline; events become a timeline or history |
+| Relationships | Which facts only make sense together: a shortage and its line, a refund and its payment, a price and its variant? | Adjacency. These stay in one subject and never split across separate cards |
+| Missing, not applicable, zero | Is a value unknown, irrelevant to this record, or a real zero? | "Not set" versus `0`; a not-applicable row is omitted, not printed empty |
+| Units and precision | Currency and minor units, percentage base, whole quantities | The value primitive, its precision and tabular alignment |
+| Text length | Longest names, translations, identifiers | Wrapping, truncation with full text available, track widths |
+
+## Find the decision
+
+Name who looks at the screen, what they decide or do next, and how often. An
+operator working a queue scans many records for exceptions and acts on one. A
+manager opening an overview wants to know whether things are on track and where
+to look. A catalogue editor configures structure that later sales depend on. The
+same records produce different views for each; write the one you are designing
+for.
+
+## Questions per data shape
+
+- **One figure.** Compared with what: the previous period, a target, a limit? A
+  figure without a baseline cannot be judged. If no honest baseline exists, say
+  so instead of inventing a trend.
+- **A series.** Is the shape the message (a dip, a ramp, seasonality) or only
+  the latest value? Do the series period and the comparison period match?
+- **A collection.** Which column would the user sort by first? Which rows need
+  attention, and how does a row show it? What identifies a row, and what lets the
+  user decide about it without opening it?
+- **A record.** What state is it in now, what blocks it, and what is the next
+  action? Which facts are evidence and which drive the action?
+- **A lifecycle.** Which stage is current, which are complete, and what stops
+  progress? Completed stages rarely need equal weight with the current one.
+
+## Write the data brief
+
+Keep it to a few lines in the view spec. It is the input to every later choice,
+so state facts from the records, not intentions.
+
+```text
+Decision: <who> decides <what>, <how often>
+Subject: <entity>; typical <n> children, largest <n>
+Facts that matter: 1) … 2) … 3) …
+Anomaly: <the record or value that breaks the pattern, and what the view must make visible>
+States: show <…>; collapse <…>; omit <zero or not-applicable …>
+Must stay together: <fact + fact>, <fact + command>
+Unknowns: <data the records do not contain; state them, never invent them>
+```
+
+## Example: an order with a split shipment
+
+An order whose line is reserved across two warehouses, with one unit short:
+
+```text
+Decision: an operator decides what can ship now and what blocks the rest, many times a day
+Subject: order; typical 2 lines, largest 6; up to 2 locations
+Facts that matter: 1) units that can ship from each location now 2) the shortage and the line it affects 3) whether payment allows release
+Anomaly: one line split across two locations; the split belongs on the line, not in two unrelated lists
+States: show reserved, short and shipped where non-zero; omit "0 returned"; collapse fully shipped lines
+Must stay together: shortage + its line + location; payment state + the release command
+Unknowns: carrier tracking is not in the records
+```
+
+That brief already rules out a facts card repeating the header, per-line counters
+for every lifecycle stage, and a generic "items" table that separates goods from
+their location. Owner selection then follows from
+[screen decisions](screen-decisions.md) and the
+[order and invoice owner map](commerce-composition.md).

package/docs/consumer-skill/references/design-contract.md

@@ -68,6 +68,7 @@ These base measurements use the shipped roots; spacing scales once through
 | Independent subject regions | `2xl`, 24px | Page body, TwoColumnLayout, resource, workspace and settings subjects |
 | Page header/body separation | `3xl`, 32px | Page composition |
 | Surface header/body/footer | Surface-derived regional gap | Card or overlay anatomy, independent of peer gaps |
+| Live table outer / interior cell insets | Small surface / row inline tiers, 16 / 12px | Table head, body and footer cells; row density changes only block rhythm |
 
 Generic Stack and Grid keep their existing defaults; choose their semantic gap
 for the relationship they host. A Card's regional gap derives from its surface
@@ -92,7 +93,7 @@ custom render content rather than forcing every heading onto the admin scale.
 | Collection density | Row block padding and minimum height | Inline padding, text size, surface inset or corners |
 | Item size | Legacy text/media scale, including provider fallback | Vertical row density |
 | Control size | That owner's action/field geometry | Page rhythm or surface padding |
-| Surface inset default/compact | Full/half surface roots | Row density |
+| Surface inset default/compact | Rich surface roots / compact collection shell (24/8px defaults) | Row density |
 | Surface inset flush | Delegate padding to public regions | Remove Input padding or create a third density |
 | `--space-scale` | Shared gaps, inline insets and surface padding | Row block/control-height density |
 | `--density-scale` | Action/control heights and row block padding | Inline room or primary text hierarchy |
@@ -102,14 +103,16 @@ multiply once by `--space-scale`. Descriptions have no extra margin. These are
 copy gaps; larger section and action-cluster gaps remain on their own owners.
 The [token reference](tokens.json) records the installed defaults and vocabulary.
 
-Outer Card, popup and Command shells use `rounded-radius`: the shadcn root,
-12px by default. Input, Button, Select/facet triggers, collection highlights,
-navigation rows and intentional nested bodies use the shared `rounded-inner`
-role, 9px by default. It derives at 0.75× and is bounded by one quarter of the
-smaller action/control base height, scaled by density. A larger global root
-therefore cannot turn short controls into capsules. See [the exact theme
-recipe](theming.md). Density can tighten the inner bound; it does not change
-outer corners. Spacing scale and padding do not select another radius tier.
+Corners derive from the one shadcn root, `--radius` (12px by default). Input,
+Button, Select/facet triggers, badges, collection highlights, navigation rows and
+nested bodies use the default `rounded-radius`, the root itself. Card, popup and
+Command shells use the larger `rounded-surface` (4/3 of the root, 16px). See [the
+exact theme recipe](theming.md). Density, spacing scale and padding do not select
+another radius; only small mechanics use the proportional xs/sm/md steps.
+
+Short tooltip labels use the existing compact `rounded-radius-xs` tier
+(0.4× the radius root, 4.8px by default) and an arrowless 4px anchor gap. They
+remain inverse contextual labels rather than substantive popup surfaces.
 
 Use the public component defaults instead of adding radius classes to callers.
 Joined edges may reset their meeting corners. Circular indicators and avatars

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

@@ -35,6 +35,16 @@ they do not establish an unsupported capability. Read the suggested owner's
 choose/avoid guidance and inspect its contract before choosing. Unknown-only
 queries, API-like CamelCase names and explicit import paths do not recover.
 
+An unpublished import path is resolved only from deterministic evidence: the
+missing package prefix (`base/cards`), a catalogue path alias, the family's
+published singular or plural spelling (`base/card` → `base/cards`, `base/charts`
+→ `base/chart`) or a trailing segment naming one exported component
+(`features/data-table` → `DataTable` in `features/table`,
+`blocks/commerce/order-header` → `OrderHeader`). The result then reports
+`importResolution` with the requested path, the canonical `import`, the reason
+and any named `symbol`. Use that canonical import in code. A path without such
+evidence, such as `features/unknown`, still returns no owner.
+
 If there are no useful related owners, shorten the query to the main
 responsibility or an exact symbol, then remove the layer filter. No result does
 not prove the package lacks that responsibility. Read the selected result's choose/avoid guidance and
@@ -77,7 +87,7 @@ content; application chrome and analytics are separate responsibilities.
 
 For geometry, `radius`, `border radius`, `control corners` and `control heights` select the existing UIProvider/theme
 boundary guidance; `copy gaps` selects Structure. Their focused references explain
-outer/inner corner roles, corresponding sizes, inherited defaults and normal/dense
+surface/default corner roles, corresponding sizes, inherited defaults and normal/dense
 copy rhythm even when no executable recipe matches the query. `page padding`
 selects Page; `card padding` selects Card. Read those owners before adding local
 gutters, reducing normal Card insets or rebuilding their headers/footers.
@@ -124,6 +134,12 @@ Read each declaration relative to the installed package root, for example `node_
 
 ## Map cooperating components
 
+`expandable form sections`, `collapsible sections` and `editable sections` select
+Accordion's coordinated disclosure anatomy and the retained-content recipe.
+Inspect the exact compound parts when a bounded convenience wrapper lacks a
+needed seam. `custom composition` routes to passive structure guidance; it does
+not mean Stack replaces the semantic controls/blocks inside that composition.
+
 The [composition mapper](composition-mapping.md) resolves explicit role tags into
 qualified owners and an advisory region tree. Use it after decomposing a screen
 into subjects, or inspect the available roles before choosing components:
@@ -148,10 +164,18 @@ node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-componen
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs ThemeScope --import themelia-react-ui/ui-provider
 ```
 
+Default inspection includes meaningful inherited component behavior before
+native/ARIA noise. All inherited props remain available through exact --prop;
+read omissions before concluding that an API is absent. For example, inspect
+AccordionContent's keepMounted rather than assuming form fields must unmount.
+
 Use `--import` to select an exact public contract when a symbol has several
-owners. `--prop` requests one exact property; `--limit` bounds the initial list
+owners. `--prop` requests exact properties: repeat it or separate names with
+commas (`--prop title,primaryAction`); `--limit` bounds the initial list
 of props. Read reported omissions before assuming a property is absent. Unknown
-exports/props and ambiguous unqualified contracts fail explicitly. Aliases can
+exports/props and ambiguous unqualified contracts fail explicitly. A public hook
+or helper such as `useOverlayVisibility` has no component contract; the error
+names the declaration file and import that hold its signature. Aliases can
 share implementation while distinct exports such as the two ThemeScope owners
 have different APIs.
 

package/docs/consumer-skill/references/domain-structures.md

@@ -0,0 +1,124 @@
+# Token-backed domain structures
+
+Use when a business relationship needs its own structure: an allocation ledger,
+stock comparison, schedule, reconciliation or other subject whose arrangement is
+more specific than a ready-made block. Start with [screen decisions](screen-decisions.md)
+and the installed component discovery tools. Mostly compose public base
+components, layout blocks, typography and value primitives; add semantic JSX and
+Tailwind where the subject needs custom tracks, grouping or responsive behavior.
+This is a normal application seam, not a fallback that requires a missing API.
+
+## Divide the work deliberately
+
+| Requirement | Owner |
+| --- | --- |
+| Route identity, commands, gutters and page regions | Page and the chosen app layout |
+| A titled/framed/transparent subject with aligned insets | Card; paint and padding are independent |
+| Routine stack, wrapping actions, equal tracks or column split | Stack, Grid, AdaptiveGrid, TwoColumnLayout |
+| A product-specific comparison, local container adaptation or irregular tracks | App component with semantic JSX and Tailwind on its own elements |
+| Display text and formatted values | Heading, Text, Money, Number, Date and related primitives |
+| Selection, commands, menus, forms and overlays | The relevant public interactive owner and its supported parts |
+| Business calculations, allocation rules and accepted state | App/domain logic or authoritative backend results |
+
+Do not recreate Input, Menu, Button, Card anatomy or keyboard behavior in custom
+markup. An app-owned region can still contain these owners. Extract a component
+when it gives a coherent domain contract; a new file or custom component count
+does not itself improve a screen.
+
+## Choose classes by responsibility
+
+Use `inspect-tokens.mjs` to verify the installed utility spelling and overrideRoot.
+The following are shipped classes, not new variables:
+
+| Intent on app-owned markup | Vocabulary |
+| --- | --- |
+| Close label/supporting copy | `gap-dense`, `gap-normal` or the equivalent Stack gap |
+| Related values/fields | `gap-space-xl` |
+| Separate subjects | `gap-space-2xl` |
+| A custom surface region | `p-surface`, `px-surface`, `py-surface` when that element owns the inset |
+| A custom plain row | `px-row-x`, `py-row-y` when its row inset is required |
+| Layout and responsive geometry | `min-w-0`, `grid`, `grid-cols-[…]`, `@container/name`, named container queries, wrapping and overflow |
+| App surface/foreground | `bg-card text-card-foreground`, `bg-background text-foreground`, `bg-sidebar text-sidebar-foreground` |
+| Quiet copy / structural rule | Text type="secondary" / `border-border` |
+
+Pick the relationship before the size. Page/Card already owning an inset means
+the inner subject does not add `p-surface`. Flat Card retains md padding unless
+explicitly changed; use padding="none" only under another inset owner or for an
+intentional flush region. Transparent and painted peers can use the same inset
+so their heading/body edges align.
+
+Continuous sections can share one padded host and an unpadded internal Stack.
+Separate padded flat Cards can accidentally add bottom inset + peer gap + top
+inset; a valid token on each layer does not justify that combined distance.
+
+Use a local container query when a subject can live in either a main column or
+a narrow aside. Viewport width alone does not establish available space. An
+arbitrary grid track or breakpoint can express product geometry; arbitrary
+spacing, text sizes, radius or state palettes usually recreate a shared role.
+Do not force essential rows into horizontal scrolling merely to retain every
+desktop column. Preserve the important identity/value relationship in the
+narrow composition and keep other detail accessible.
+
+## Customize the theme, not each control
+
+Keep shadcn surface/foreground pairs and use component tone/status props.
+Use Heading/Text props instead of typography classes on imported text owners.
+Use supported sizes/insets on controls and surfaces. Do not add local hover,
+focus, selected or disabled recipes to a public component.
+
+Typography props are not interchangeable: Heading selects semantic level and
+visual size with tag/size; Text has its own supported tags and weight/type
+contract. Inspect the exact export instead of assuming that a prop supported by
+one typography owner exists on another.
+
+Custom table cells retain those primitives' alignment and flow. Match the column
+header and every line of the cell deliberately: a right-aligned Money above
+left-aligned cost copy under a left-aligned header creates three conflicting
+axes. Preserve the table's chosen alignment or use its supported column seam;
+do not assume the surrounding cell overrides a child primitive's own default.
+Keep primary prices/SKUs readable and move secondary detail to its inspection
+subject when it prevents useful comparison.
+
+Canonical roots are the settings: `--space-scale` changes shared gaps/insets;
+`--density-scale` changes action/control/row geometry; `--surface-x` and
+`--surface-y` own surface room. They have different responsibilities. A smaller
+mobile viewport does not automatically justify globally shrinking all of them.
+First repair duplicated insets, wrong group spacing and low-priority content.
+When the product needs a shared responsive spacing policy, set the appropriate
+existing root at its app/theme boundary in CSS and review affected siblings.
+Preserve usable controls and copy; avoid component-specific token copies.
+
+Use derived utilities as classes. Never override or read derived `--spacing-*`,
+`--radius-*` or `--container-*` aliases inside a scoped formula: they resolve at
+the root. If custom drawing needs a formula, derive from the canonical roots
+and apply each scale once. ThemeScope handles scoped/portaled theme inheritance;
+do not copy computed variables through JavaScript.
+
+## Executable example
+
+The [allocation subject](../examples/token-domain-structure.tsx) combines public
+Card/Stack/Text/value owners with an app-owned definition grid. It compares
+reserved quantities across locations, a relationship no block represents. Goods
+that share one fulfillment status and ship-from location, with the commands that
+move them on, are a `FulfillmentGroup` instead; see the
+[order and invoice map](commerce-composition.md). Warehouse groups
+and unavailable quantities stay near their goods. The custom grid changes at
+its own container width; no control or surface recipe is replaced. The caller
+supplies accepted quantities and optional public actions; the example does not
+invent inventory allocation or fulfillment policy.
+
+The [assessment comparison](../examples/custom-composition.tsx) is a smaller
+example, and [commerce lines](../examples/commerce-lines.tsx) demonstrates a
+block's typed content seam. Run these through the consumer checker after
+adapting them. Ensure the app compiles its own Tailwind utilities as described in
+[theming](theming.md); shipped component CSS does not compile app-authored classes.
+
+## Inspect the result
+
+Review actual hierarchy, peer content edges, spacing and wrapping in narrow/wide
+parents, light/dark themes and independently changed spacing/density. Inspect
+the image; zero overflow is not enough. Open a menu/editor in the active scope,
+then verify keyboard/focus, invalid/disabled and accepted/error states. If a
+supported public composition still drifts, report the exact owner and a minimal
+reproduction so the shared component is repaired instead of patched with local
+CSS. See [review](review.md) for separate source, appearance and interaction proof.