themelia-react-ui 2.0.3 → 2.0.5

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

@@ -52,6 +52,38 @@ requests one shared boundary. Setting both does not add a second line or a blank
 body strip. Real body/alert regions retain their distinct requested boundaries;
 an explicitly expandable card retains its collapse region.
 
+## Semantic roles
+
+Choose spacing by the relationship between content, before choosing a gap tier.
+These base measurements use the shipped roots; spacing scales once through
+`--space-scale`.
+
+| Relationship | Default | Owner |
+| --- | --- | --- |
+| Structural title/supporting copy | `normal`, 4px | Headed owner or custom copy Stack |
+| Dense supporting copy | `dense`, 2px | Row/menu copy group |
+| Ordinary commands | `md`, 8px | Page, record and workspace command groups |
+| Compact row affordances | `xs`, 4px | Row action group |
+| Related fields/content | `xl`, 16px | Form or related-content group |
+| 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 |
+
+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
+inset tier and remains independent of the gap between separate Cards. For Card,
+omitted `padding` means `md` (24px); `sm` is 12px, `lg` is 32px and `none` removes
+insets while retaining the 24px default regional gap. Explicit `gap` overrides
+that regional recipe. The general surface vocabulary also has a 16px tier; it is
+not an additional Card padding prop.
+
+Typography follows route, subject and subsection roles at 20/16/14px before
+customization. Body and supporting copy normally use 14/12px. Semantic tags stay
+independent of visual size; supported `size`, typography/provider defaults and
+CSS text-root overrides remain available. Density changes row/control geometry,
+not the primary text hierarchy. Preserve a deliberate website/hero emphasis or
+custom render content rather than forcing every heading onto the admin scale.
+
 ## Keep these choices independent
 
 | Choice | Purpose | Does not choose |
@@ -60,7 +92,7 @@ an explicitly expandable card retains its collapse region.
 | 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 |
@@ -70,14 +102,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

@@ -14,9 +14,9 @@ node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.
 
 For a copied skill, replace the script path with that copy's `scripts/find-components.mjs`. Copy the complete skill folder: the script resolves its adjacent `references/public-api.json` relative to itself, regardless of the working directory. It needs Node compatible with the package's engine requirement, not an npm/global CLI or extra dependency.
 
-Queries accept multiple words, quoted or separate. Every term must match metadata
-as a word; `stat` does not match `state` or `status`. An unknown term produces
-empty results. Exact imports and case-exact exported names such as `Table` or
+Queries accept multiple words, quoted or separate. Strict `results` require every
+term to match metadata as a word; `stat` does not match `state` or `status`. An
+unknown term leaves strict results empty. Exact imports and case-exact exported names such as `Table` or
 `Empty` select their precise contract. Ordinary task nouns `table` and `empty`
 retain DataTable/DataView and EmptyState alongside the base anatomy. Exported
 types and helper symbols remain available by their exact API name; documented
@@ -26,9 +26,28 @@ component symbols and curated aliases drive task recommendations.
 Foundations but filters under `--layer base`. `--limit` accepts 1–100 and defaults
 to 5. Invalid flags/options or incompatible indexes exit nonzero on stderr.
 
-If a query returns no results, shorten it 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
+When a natural-language query has no strict matches, the finder may add bounded
+`related.results` separately. For example, `member workspace` can suggest the
+workspace owner while explicitly reporting `workspace` as matched and `member`
+as unmatched. These are incomplete context suggestions, not proof that the owner
+implements the whole request. Unmatched terms describe missing metadata evidence;
+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
 alternatives, then follow `nextReads`; do not load every reference. For routine compact searchable selection, search
 `PopoverMenu` or `compact searchable selection`; surface adjectives describe
 variants, not permission to rebuild the owner's padding.
@@ -44,7 +63,7 @@ description matches. Start with responsibilities such as `record directory`,
 `comparison table`, `identity cell`, `fact list`, `page header`, `query toolbar`
 or `theme boundary`. Read choose/avoid and app-owned responsibilities before
 deciding; a directory result does not require DataView when its workflow differs.
-Unknown terms still return no result; no fuzzy API or guessed prop is invented.
+Unknown terms never become strict matches; no fuzzy API or guessed prop is invented.
 
 Task language also includes `dashboard KPIs`, `dashboard metrics`, `revenue
 overview`, `statistic cards`, `usage statistics` and `single resource page`.
@@ -68,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.
@@ -87,6 +106,14 @@ new code with the replacement. The public index carries the same map per family.
 Exact guide aliases precede generic overlap, and unrelated family pages
 do not fill the result merely to reach three entries.
 
+The optional `related` object leaves strict `total` and `results` unchanged. It
+reports an explanation, its own `total` and bounded `results` with `match:
+"partial"`, `matchedTerms` and `unmatchedTerms`. Term coverage ranks first, then
+the existing owner score and import ordering. These suggestions follow the same
+layer filter and limit, and use the same published owners and focused reads;
+package/path vocabulary alone cannot suggest an owner. The static finder shows
+their incomplete coverage separately from full matches.
+
 `nextReads.declaration` is relative to the installed package root.
 `nextReads.references` and `nextReads.examples[].file` are relative to this
 skill folder, so they also work with a complete copied skill. Examples report
@@ -105,6 +132,80 @@ owners and focused reads; declarations establish actual props and behavior.
 
 Read each declaration relative to the installed package root, for example `node_modules/themelia-react-ui/dist/components/base/cards/index.d.ts`, following its relative exports as needed. Copying this skill copies metadata, not the declaration tree: use declarations from the same installed package version. Never combine metadata from one version with another version's declarations.
 
+## 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:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --roles
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --pattern record-detail --main invoice-lines --aside facts
+```
+
+Read its unresolved requirements, surface decisions and peers; the finder and
+API inspector remain useful for responsibilities outside mapped coverage.
+
+## Inspect a selected component
+
+The finder chooses owners. The dependency-free inspector retrieves a bounded,
+versioned API contract for an exact exported component without loading the full
+catalogue or manually chasing its declaration barrel:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs DataTable --import themelia-react-ui/features/table
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs DataTable --import themelia-react-ui/features/table --prop onRowSelectionChange
+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 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. 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.
+
+The generated `component-contracts.json` comes from the existing TypeScript/prop
+documentation pipeline. Types, call signatures, generic parameters, overloads
+and mode-dependent requirements remain visible. A prop required in one union
+branch is not universally required. Defaults are only those documented by that
+pipeline; an unknown default is not inferred. Native attributes and named helper
+types still lead to installed declarations where the bounded contract needs
+more detail. Inspect callback types and controlled/default state before adapting
+a recipe; sharing a visual shape does not mean controls share a value contract.
+
+The copied inspector reads its adjacent shared metadata, like the finder. Verify
+the complete copied bundle and installed identity first. It does not install
+dependencies, alter an app, or add an editor/type-checking runtime.
+
+## Inspect theme vocabulary
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-tokens.mjs surface --limit 8
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-tokens.mjs radius --limit 5
+```
+
+Token lookup reads the existing generated token index. It distinguishes public
+structural roots and advanced settings from derived utility vocabulary. A
+utility match does not become an override root. Unreported semantic theme values
+must be read from the installed stylesheet and [theme guide](theming.md); the
+tool does not invent a palette. The tokenization skill owns changing these
+shared roles and verifying the effects across controls/surfaces and portals.
+
 `ThemeScope` has distinct contracts. Root and `themelia-react-ui/ui-provider` export the basic CSS-inheritance boundary with native div/style props and portal hosting. `themelia-react-ui/features/theme-tweaker` exports the advanced theme-definition scope. Inspect the result's responsibility and that exact family's declaration before selecting props.
 
 The index retains schemaVersion/discoveryVersion 1; optional family `recipes` and `references`