themelia-react-ui 1.0.0 → 1.0.2

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

@@ -16,12 +16,158 @@ keep placement, width, wrapping and overflow with the surrounding composition.
 | Reusable subject presentation | Blocks |
 | Editing/selection/async lifecycle | Features with app callbacks |
 
+## Compose from the task
+
+Identify the user's next decision before selecting components. Establish fixed
+context (account, parent entity, workspace), editable query criteria, leading
+information, page/collection/record commands, and loading/empty/error/edit states.
+Then assign owners. A task may require a comparison table, a compact directory,
+a detail workspace or a form; they need different information hierarchies.
+
+| Decision | Use when | Alternative / boundary |
+| --- | --- | --- |
+| DataView | Its coordinated query, view and collection lifecycle fits | DataTable with app-owned query transport and native toolbar slots when coordination differs; base Table for presentation without TanStack behavior |
+| ResourceCell | Identity inside a table cell | Item for independent list entries; MetadataList for label/value facts about one subject |
+| Page / application shell | Route identity, navigation, content bounds and page commands | Card for an independent subject within that route; do not repeat the same heading merely to frame a table |
+| Card | One subject needs a frame and headed regions | `surface="flat" padding="none"` inside an existing boundary; nested DataTable uses its own `surface="flat"` |
+| Metric / MetricGrid / MetricBar | A KPI needs formatted value, comparison/trend or peer layout | UsageCard for used/limit quotas; InlineStat for one plain fact, MetadataList for several record facts |
+| FormField / InlineEdit | A field needs label/hint/error, or isolated save/cancel | Complete feature/overlay for a workflow; app form owns whole-record submission |
+
+For a DataTable composition, put queries in `topbarContent`, exports or collection
+tools in `topbarEnd`, selection commands in `bulkActions`, and record commands
+in `rowActions`. Other arrangements are valid when the product has a distinct
+query region; choose one owner deliberately and keep queries close to their
+results. DataView already owns coordinated filtering; do not add a second filter
+store around it without inspecting its contract.
+
+Fixed scope and mutable criteria are different states. A collection reached
+inside one business can show that business as context/navigation; query controls
+then narrow that scope. If business is an editable filter, clearing it may widen
+the collection. The app owns this meaning and transport. Do not accidentally
+present fixed scope as a removable criterion or repeat it in every region.
+
+Use primary identity plus task-critical supporting facts in compact rows.
+When columns disappear, preserve access to other facts through detail/disclosure
+or supported comparison controls. Avoid automatically appending every hidden
+column to identity metadata. There is no universal row-line limit: long names,
+accessibility needs and the task can justify richer rows. Explain the priority.
+Custom ResourceCell metadata is caller content; use shared supporting typography
+and CellStack where its smaller secondary-value contract fits.
+
+Commands need explicit importance as well as scope. PageActions does not infer
+primary tone from a label such as “New contact”; choose `tone="primary"` when
+that is the route's main command. Permissions and destructive intent remain
+application decisions. A back link, export and destructive command should not
+all inherit the same visual emphasis by accident.
+
+| Drift | Better decision |
+| --- | --- |
+| Same parent named in header, context strip and fixed filter | One contextual lead; repeat only where it clarifies a separate task |
+| Every hidden column becomes identity metadata | Prioritize visible facts and retain access to the rest |
+| Repeated route title on an otherwise untitled table Card | Route header plus native collection surface |
+| Child and parent both add the same gutter/inset | Assign visible space once at its owner |
+| New local controls to imitate an existing workflow | Inspect the public feature/parts/callback seams first |
+
+See the [scoped directory recipe](../examples/scoped-directory.tsx) and
+[workflow explanation](workflows.md#scoped-directory). Review decisions using
+[review and checks](review.md); valid alternatives should preserve task semantics
+and public anatomy, not imitate one screenshot.
+
 Use the exact family declarations from public-api.json. Catalogue URLs and source folders are not import contracts.
 
+For dashboard KPIs, revenue and statistic cards, read the focused
+[analytics selection and recipe](analytics.md). Metric's card variant,
+MetricGrid's default peers and UsageCard own their surfaces. A distinct custom
+Card subject remains valid; compare the complete subject contract before rebuilding
+formatting, hierarchy or request-state presentation from lower text primitives.
+
+## Public websites and service overviews
+
+Compose a landing page or public website from its content. `Container` owns the
+centered measure and inline gutters; `Section` owns semantic content groups and
+their sibling rhythm. Stack/Grid arrange copy, actions and peer subjects. Shared
+Heading/Text roles preserve typography while heading tags express document order.
+Choose `Page` when its route identity, commands and composition slots fit; choose
+Container/Section when content leads. AppLayout supplies application chrome when
+the product needs it. These are application choices, not required website shells.
+
+The app owns section order, hero content, media, link destinations, responsive
+placement and brand theming through existing semantic roots. Keep one inset owner:
+Container supplies inline gutters, a site boundary may supply semantic block
+padding, and each independently framed subject keeps Card's default inset.
+
+A service offer or pricing option is a legitimate Card subject. Put its name and
+description in the header, price through Money, and navigation in the footer seam.
+Metric/MetricGrid represent observed KPIs and comparisons; a selling price belongs
+to the offer's content. Preserve application-owned currency, billing terms and
+destinations. See the typed [website recipe](../examples/website.tsx), which uses
+ordinary document scrolling and a responsive service grid with real link actions.
+
+## Typography and rich content
+
+Choose Heading, Text, DisplayLabel, Label and TextLink from the published
+typography family by role. Set semantic tags independently of visual variants;
+heading order describes the document, not a desired font size. Labels associate
+controls with stable IDs. Money, Date, Email and other value primitives own
+formatting, locale/unit handling and empty-value fallbacks; zero is real data.
+The app owns accounting, timezone policy and the meaning of unavailable values.
+
+Primary row values and labels use the shared default text size. Compact metadata,
+form hints and row descriptions use smaller secondary copy; structural panel
+descriptions use default-sized secondary text. Typography adds no outer margins.
+Native editable text retains its responsive field recipe. Do not resize it to
+imitate a display label or use density to make all text smaller.
+
+RichText from `themelia-react-ui/typography/rich-text` displays sanitized HTML,
+with a scoped reading rhythm inherited from typography and theme roots. Use
+`tag="div"` for HTML containing paragraphs/headings/lists; its default `p` tag
+is appropriate only for inline content. The allowlist strips arbitrary styling,
+embedded media and unsafe links; it is not a Markdown parser or email-layout
+renderer. Keep outer width/padding on the surrounding structure. RichTextEditor
+owns editing; EmailComposer owns structured email/variable/delivery contracts.
+Read the relevant declarations and [integration](integration.md) before choosing
+the content owner. Embedded React UI can opt out of reading rhythm through
+`not-typeset` or `data-not-typeset` on its subtree; those opt-outs do not bypass
+HTML sanitization or establish a separate typography system.
+
+### Visual heading emphasis
+
+`Heading tag="h1"` preserves the compact admin default. For website/hero copy,
+choose `size="3xl"` or `size="4xl"`; sections may use `size="xl"` or `"2xl"`.
+The semantic tag, visual size and surrounding Section/Stack gap are independent.
+Existing text-size classes remain supported overrides. Section owns rhythm,
+Container owns measure/gutters, and application utilities may own a hero's outer
+padding or background. No additional section/hero theme tokens are required.
+See the [website example](../examples/website.tsx) for both hero and section emphasis.
+
+
 ## Card anatomy
 
 Card surface="card" is the ordinary bordered surface; surface="framed" retains its ring recipe; surface="flat" padding="none" composes within an existing boundary. headerPlacement="frame" places title/icon/actions above an inset body, retaining default corners and using rounded-inner on that body.
 
+Choose one ordinary Card surface through UIProvider's `card.defaultSurface` and
+let sibling subjects inherit it. Explicit per-card surfaces win: mixing `card`
+and `framed` intentionally changes their visible treatment. Header placement is
+independent: `inside` keeps the heading with the body; `frame` puts context and
+commands on the outer frame above the inset body. Use `icon={<Icon />}` for a
+routine heading glyph and plain `title`; embedding raw SVG in title JSX bypasses
+the owner's icon sizing. Custom titles remain appropriate for richer content.
+
+Card `gap` owns spacing between regions; `contentGap` owns direct body-child
+spacing; `textGap` owns title/supporting-copy rhythm. Region spacing defaults to
+`xl` (`md` for `padding="none"`). Use a semantic region gap for compact cards
+instead of resetting padding or adding local margins.
+
+Ordinary independent cards omit `padding` and retain `md` (the full surface
+inset, 20px at default roots). `sm` is half that inset (10px), for a deliberately
+compact subject; it is not the default for forms, settings, metrics or resource
+pages. Component size and
+density do not choose Card padding. `lg` uses 1.8 times the inset (36px), while
+`none` removes it. All sizes follow the surface roots and space-scale.
+UIProvider can configure both
+`card.defaultHeaderDivider` and `card.defaultFooterDivider`; explicit per-card
+booleans win. Header/footer-only cards still render one shared divider.
+
 Use titleSuffix for status/count/version badges. Long titles/suffixes wrap through the shared owner; no literal spaces/local margins to manufacture gaps. headerAction/actions are trailing controls, headerStart pre-title context. footerSlot/footer definitions own card-level actions; footerDivider owns the rule and inset. Do not simulate a footer inside children. SmartCard and ContentBlock are deprecated migration names; use Card in new code.
 
 Reusable blocks/features stay card-free unless their explicit purpose is a card. Frame them at the composition boundary.
@@ -32,6 +178,18 @@ Shells own gutters, surfaces own padding, sections own rhythm, Stack/Grid own si
 
 Grid exposes viewport columns; AdaptiveGrid responds to parent width and a semantic minimum column size. GridCell spans belong to the nearest Grid. Keep narrow DOM order meaningful. Horizontal Stack wraps by default; disable it only when overflow is intentionally handled. Tailwind is appropriate for min-w-0, positioning, overflow and drawing geometry.
 
+Independent surfaces need peer rhythm, usually `gap="xl"`; Stack's default
+`md` is general sibling spacing, not a card-grid prescription. Framed Card rings
+extend outside layout rectangles, so two rings can consume a small DOM gap.
+Inspect visible edge clearance in both axes rather than accepting token use alone.
+Copy gaps normal/dense are for supporting text, not spacing independent cards.
+
+MetadataList owns medium-weight labels and normal-weight routine values. Its
+compact density tightens gaps/rows without shrinking primary values. Plain values
+and typed descriptors retain the shared roles; React nodes, `display` and `render`
+preserve supplied typography. Keep custom formatted values consistent with value
+primitives rather than replacing labels and values with undifferentiated Text.
+
 ## Menus and controls
 
 PopoverContent type="display" owns substantive-content padding; type="menu" compact collection padding around already-padded rows. Popover and Command share inset="default" and inset="compact" paradigms. Mixed searchable shells use inset="flush"; public header/search/list/footer anatomy owns its insets automatically. CommandInput composes the public Input for control geometry and focus styling; its search region adds only outer spacing. Do not pass padding through className, contentClassName or inline styles. Compact header controls and footer actions align with row highlight edges; header text and footer captions align with row labels. Use PopoverHeader start for a leading control and PopoverFooter caption for supporting content alongside trailing action children. Dividers use the same semantic recipe. density selects vertical row rhythm without changing inline padding. ActionMenu owns action definitions, PopoverMenu searchable selection, DropdownMenu bespoke menu anatomy. Shared appearance preserves their accessible menu/listbox/dialog behavior.
@@ -44,6 +202,13 @@ PopoverContent type="display" owns substantive-content padding; type="menu" comp
 | density="compact" / "default" / "comfortable" | Collection row block rhythm, independent from inline spacing |
 | size="sm" / "md" / "lg" | Supported control's scale; consult its declaration and provider precedence |
 
+Input, Button, Select and filter-facet triggers share bounded inner corners
+and corresponding heights; Card and popup shells use the global outer radius. Omitted sizes inherit the provider; explicit sizes win.
+Keep action/control roots equal when those controls adjoin. Compact menu rows,
+surface insets and control sizes remain independent; density can tighten the
+inner-radius height bound without changing outer corners.
+Inset segmented children use the supported compound owner's same-height frame.
+
 PopoverContent defaults to display/default; Command defaults to compact. An explicit PopoverContent type controls anatomy; explicit inset controls padding and takes precedence over the type's inferred inset. Without type, compact implies menu, other insets imply display. Put type="menu" inset="flush" on PopoverContent for a headed searchable picker. Popover is the interaction root and receives no surface props. PopoverMenu already assembles that picker anatomy; use its declared selection/search props. ComboboxPopup is flush because ComboboxList owns its inset. Do not add another wrapper inset around a normal collection list.
 
 At shipped roots, compact shell padding is 8px; row inline padding is 12px; default row block padding is 8px and minimum height 36px. Compact/comfortable rows use 6/10px block padding and 32/40px minimum heights. Content can grow when it wraps. These are token-derived measurements, not app constants. Flush compact header/footer shell padding matches the list (8px inline). Header text bodies without a leading control and footer captions add the row inset once, aligning text at 20px. Actions keep the 8px shell edge. Nested public slots do not repeat these insets.
@@ -62,8 +227,8 @@ Use exact themelia-react-ui paths. Presentation imports use blocks/<family>, rep
 ## Copy rhythm
 
 For title/supporting-copy rhythm use `textGap="normal" | "dense"` on Card,
-PageHeading and public surface headers; normal is 8px and dense is 4px before
-spacing scaling. Item/ItemContent and menu popover headers default to dense.
+PageHeading and public surface headers. The installed token reference records
+their unscaled defaults. Item/ItemContent and menu popover headers default to dense.
 Stack/Grid accept the same semantic gaps, including responsive objects and
 axis overrides. Keep surface insets and action-cluster gaps on their owners;
 do not add a second margin to descriptions.
@@ -168,3 +333,55 @@ adaptTo="container" inside Container/PageViewport to adapt at 48rem of usable
 parent width while preserving main-before-aside DOM/focus order.
 
 See the installed [workspace recipe](../examples/app-layout.tsx).
+
+PageViewport owns scrolling and adds no padding. Page defaults to `gutter="lg"`
+and `padding="lg"` (36px at shipped roots), so it owns inline/block space once.
+`narrow` selects centered `md` width; explicit `maxWidth` wins. Header copy
+defaults to dense; `textGap="normal"` is an explicit alternative. Do not assume
+an app shell supplies gutters because it supplies a viewport. Set `gutter="none"`
+only when an actual parent Container/surface supplies the inline inset, such as
+StackedLayout's contained mode. Block padding remains independent.
+That contained measure uses the same large gutter as Page; ordinary Container
+defaults remain unchanged.
+
+Select width from the task: a single focused resource/form can use `narrow`;
+a record with a supporting aside can retain the default `lg` measure and use
+TwoColumnLayout. A wide comparison/directory can deliberately use `maxWidth="full"`.
+Setting full on every route defeats the resource measure. Do not remove Page's
+gutters to make its title touch the sidebar; align the header and body through
+the same Page. Density, container measure and page inset are separate choices.
+The [detail recipe](../examples/detail.tsx) includes `AccountDetailPage`: a
+centered resource measure, route-level commands, native Card icon/frame anatomy
+and MetadataList facts, with no duplicated subject header or gutter.
+
+Compose HeaderUserMenu in topbar `slots.headerEnd` or a local toolbar, and
+SidebarNavigationUser in AppSidebar `slots.footer` when account access belongs
+in navigation. Use SidebarWorkspaceDropdown for workspace links, or add a
+custom control through `slots.headerEnd` alongside the logo. `headerStart` and
+`headerEnd` stay inside the padded, fixed header; `slots.header` replaces it all.
+`beforeNavigation` scrolls with the links. SidebarFooter owns its rule and inset.
+LayoutSidebarProvider defaults to compact row gaps; explicit density still wins.
+WorkspaceLayout owns its own bounded content inset; do not add a padded Page
+inside it. WorkspaceRecordHeader and WorkspaceLocaleStrip align to the same
+large inline surface role. Record copy supports textGap with a dense default.
+Below 80rem of its own width, WorkspaceLayout scrolls header and body together;
+above that boundary its main region scrolls beside the sidebar. Its rail appears
+at 96rem. Supply header/drawer access to essential hidden regions on narrow
+screens; this passive layout does not create a complete mobile workflow.
+Do not infer workspace/user menus from a generic Avatar: choose their actual
+published owners and supply permitted callbacks. The app owns user/workspace data.
+
+## Task and usage summaries, editable fields
+
+| Intent | Public owner | Composition boundary |
+| --- | --- | --- |
+| Task summary and expandable checklist | `TaskCard` from `themelia-react-ui/blocks/planning` | Owns one Card and its header/body/footer; supply authoritative items and callbacks. |
+| Quotas, category/daily analytics and period selection | `UsageCard` from `themelia-react-ui/blocks/analytics/usage-card` | Owns one Card; supply data/request state and optional app footer action. |
+| Edit one saved field in place | `InlineEdit` from `themelia-react-ui/base/inline-edit` | Owns FormField and native control/action anatomy; place it inside the app's chosen surface. |
+
+Use Card's `gap` for region rhythm and `textGap` for title/supporting-copy rhythm;
+neither changes Card insets. These blocks use the canonical surface, typography,
+formatted-value and structure owners. Drawn rings and mini charts retain private
+geometry and semantic chart/status colors. Read the
+[workflow contracts](workflows.md#task-summaries-usage-and-inline-editing) and
+[typed workspace recipe](../examples/planning-usage-edit.tsx) for integration.

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

@@ -57,15 +57,36 @@ an explicitly expandable card retains its collapse region.
 | `--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 |
 
-`--gap-normal` and `--gap-dense` default to 0.5rem and 0.25rem. Their utilities
+`--gap-normal` and `--gap-dense` default to 0.25rem and 0.125rem. Their utilities
 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.
 
-Use `rounded-radius` for ordinary controls and shells; `rounded-inner` is an
-intentional nested role. Density does not change radius. Circular indicators and
-avatars retain their shape. Elevation uses the existing shadow ladder, with
-family recipes selecting the tier; do not add a separate card/menu shadow root.
+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.
+
+Use the public component defaults instead of adding radius classes to callers.
+Joined edges may reset their meeting corners. Circular indicators and avatars
+retain their shape; Badge retains its root-based recipe. Elevation uses the
+existing shadow ladder, with family recipes selecting the tier; neither a
+card/menu radius root nor a separate shadow root is needed.
+
+For appearance feedback, compare the actual open/focused state with the requested
+theme value. Inspect CSS radius resolution, dimensions, clipping, borders and
+rings as well as the computed root. Correct the visible problem at its owner;
+matching radius values alone do not establish that the result looks right.
+
+For adjoining fields and actions, keep `--height-action` and `--height-control`
+equal and choose corresponding supported sizes. Omit `size` to inherit the
+provider scale; an explicit prop intentionally takes precedence. Feature wrappers
+should preserve that inheritance rather than force `md` on one facet while its
+neighbor inherits `sm`. Deliberately different action/field roots remain supported.
 
 Structural dividers use one private recipe owner with explicit frame, anchored
 and modal roles. They share the semantic `border` root; their established strength
@@ -102,12 +123,17 @@ for logical geometry, keyboard navigation and anchored positioning; see
 3. Change an existing shared root at the intended [theme boundary](theming.md) when several related components should move together.
 4. If the public API cannot express a recurring composition, request an additive seam at that owner. Keep genuinely application-specific geometry namespaced in the application.
 
-Do not fix a shared mismatch with padding on Popover, Command, Select popup or
-Combobox anatomy, including `contentClassName`, inline styles, descendants and
+Use Card's `padding` and slots, and Popover/Command/Select/Combobox's supported
+inset and region props to correct shared padding. Preserve their internal recipe
+instead of replacing it through `contentClassName`, inline styles, descendants and
 forwarding wrappers. Likewise, do not locally replace fixed control typography
 or make descriptions carry surrounding margins. The same restriction applies
 to token-backed overrides: a semantic utility can still be used on the wrong owner.
 
+For custom copy, use `<Stack gap="dense">` around a title and description rather
+than `className="mt-space-sm"` on the description's Text. Preserve Text/Heading's
+size and semantic-element APIs; move surrounding margins to the structure owner.
+
 Theme inheritance belongs to CSS. Use ThemeScope for scoped portals; an explicit
 portal container must live in the intended boundary. Provider defaults and app
 callbacks do not form a parallel JavaScript styling system. Opening a popup is
@@ -133,9 +159,10 @@ overrides, semantic borders, and new raw spacing/control drift. The shipped
 typed examples go through the same design checks as library compositions.
 
 Those repository checks do not run automatically in a consuming application.
-Adopt equivalent component-import-aware lint rules in the application's CI, and
-run its types, build and interaction tests. The package does not strip arbitrary
-CSS at runtime or advertise a consumer audit/install CLI.
+The opt-in source checker in [review and checks](review.md) covers a smaller,
+documented set of direct-import/static-anatomy rules. Run the app's lint, types,
+build and interaction tests for broader coverage. The package does not strip
+arbitrary CSS at runtime or install audit/skill tooling globally.
 
 Static lint cannot prove alignment, readable wrapping, CSS authored elsewhere,
 unknown dynamic styles, focus restoration or callback behavior. Verify long

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

@@ -14,20 +14,108 @@ 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 candidate metadata; an unknown term produces empty results. Exact imports and exported symbols rank first. `--layer` filters the technical package layer: `foundations`, `base`, `layout`, `blocks` or `features`. This is independent of responsibility-based browse sections: `themelia-react-ui/base/structure` browses Foundations but filters under `--layer base`; a theme-tweaker recipe browses Recipes but filters under `--layer features`. `--limit` is an integer from 1 to 100 and defaults to 5. Unknown flags, duplicate options, missing values and incompatible/malformed indexes exit nonzero with an error on stderr.
+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
+`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
+component symbols and curated aliases drive task recommendations.
+`--layer` filters the technical package layer: `foundations`, `base`, `layout`,
+`blocks` or `features`. This differs from browse sections: Structure browses
+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. Read choose/avoid guidance and alternatives
-before selecting the owner. For routine compact searchable selection, search
+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.
 
-Output is deterministic JSON: package/version, query/options, total matching families and a bounded `results` list. Each result includes exact `import`, packaged `declaration`, technical `layer`, responsibility, required `optionalPeers`, match kind, exact matched symbols and up to three relevant guidance entries. Family `sections` and guidance `section` reflect responsibility-based documentation placement. Guidance carries jobs, tags, aliases, selection/avoidance, application ownership, canonical browse group/domain plus catalogue category/collection, search-section labels/symbols and alternatives resolved to exact published imports. Read the [full index](public-api.json) for all symbols/guidance. A result suggests an owner; declarations establish its actual props and behavior.
+When the same symbol is re-exported by an aggregate family, its documented
+component owner ranks first. For example, `UsageCard` selects
+`themelia-react-ui/blocks/analytics/usage-card` with no optional chart peer;
+requesting the exact `themelia-react-ui/blocks/analytics` import still selects
+that broader family. Read the reported peers and declaration for your selection.
+
+Exact curated intent aliases rank below exact imports/symbols and above generic
+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.
+
+Task language also includes `dashboard KPIs`, `dashboard metrics`, `revenue
+overview`, `statistic cards`, `usage statistics` and `single resource page`.
+`dark header` and `light header` select AppLayout shell composition.
+KPI peers select MetricGrid/MetricBar guidance; one statistic card selects Metric;
+usage quotas select the focused UsageCard leaf; a record route selects Page.
+The [analytics reference](analytics.md) explains their boundary with simple
+InlineStat facts, MetadataList and legitimate custom Card subjects.
+
+`kpi`, `metric card`, `number card`, `statistics` and `stat` expose Metric.
+`key value` and `details` retain MetadataList and InlineStat before helper rows.
+`chat` includes Message/MessageBubble as well as AiChat: choose message presentation
+or the complete prompt/conversation workflow according to the task. `markdown`
+routes to RichText's sanitized `html` display contract; the application converts
+Markdown to HTML. It does not introduce a Markdown parser or an invented renderer.
+
+For `website landing page`, `public website` or `service overview`, discovery
+selects Container/Section and the focused [website composition](composition.md#public-websites-and-service-overviews)
+recipe. Choose Page instead when its route identity/command contract fits the
+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
+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.
+
+Output is deterministic JSON: package/version, query/options, total matching
+families and bounded `results`. Each result includes exact `import`, packaged
+`declaration`, technical `layer`, responsibility, required `optionalPeers`, match
+kind, exact `matchedSymbols`, `relevantSymbols`, `nextReads` and up to three
+relevant guidance entries. Exact symbol queries keep that symbol; intent queries
+derive relevantSymbols from selected catalogue API sections and current public
+exports. An exact family import retains the complete public symbol vocabulary.
+Exact guide aliases precede generic overlap, and unrelated family pages
+do not fill the result merely to reach three entries.
+
+`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
+their actual exported recipe names and the selected public symbols they use.
+Recipe selection requires symbol overlap, not just a common family import.
+This prevents a PageHeader selection from inheriting Page-only recipes. A
+recipe's `optionalPeers` comes from its manifest and can include other families'
+requirements beyond the selected owner's peers. Inspect it before copying. A
+selected family with no matching recipe reports empty references/examples;
+use its declaration and the [full index](public-api.json), without guessing.
+
+Family sections/guidance placement follows browse responsibility. Guidance
+carries jobs, tags, aliases, choose/avoid, app ownership, browse context, API
+sections/symbols and alternatives resolved to exact imports. Results suggest
+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.
 
 `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: 1` and adds `discoveryVersion: 1`. Package name/version and peer ranges come from the published manifest; symbols and declaration paths come from live public exports; jobs and guidance come from the live consumer catalogue. Utility/root responsibilities have explicit owners when no catalogue family represents them. Optional peer requirements follow transitive local source imports, including type-only and resolved `@types` peers; the manifest supplies their compatible ranges. This describes whole-family declaration/runtime requirements, not the smaller graph a bundler may obtain after tree shaking.
+The index retains schemaVersion/discoveryVersion 1; optional family `recipes` and `references`
+are compatible additions. Package identity/peers derive from the published
+manifest, symbols/declarations from live exports, and jobs/guidance from the
+consumer catalogue. Recipe metadata derives from the existing example manifest,
+each export's actual use of exact public imports and reference-to-recipe section links; it adds no
+independent task taxonomy. Older matching indexes without recipes still work
+and return empty recipe reads. Utility/root responsibilities have explicit
+owners when no catalogue family represents them. Optional peer requirements
+follow transitive local imports, including type-only and resolved `@types` peers.
+These describe whole-family requirements; tree shaking may produce a smaller graph.
 
 Routing, records, translation, permissions and backend effects stay in the application. Discovery grants no publication or global installation authority.
+
+The index's `stylesheets` list derives from published CSS exports, including
+optional map styling. The source checker uses it instead of assuming every
+Themelia import is a component family.

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

@@ -32,6 +32,21 @@ for (const file of ['public-api.json', 'tokens.json']) {
   const selected = readJson(path.join(selectedSkill, 'references', file));
   assert.deepEqual(selected, installed, 'Copied skill is stale; refresh the complete folder');
 }
+if (fs.realpathSync(selectedSkill) !== fs.realpathSync(installedSkill)) {
+  function compareAssets(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (entry.name === '.DS_Store') continue;
+      const installed = path.join(directory, entry.name);
+      const selected = path.join(selectedSkill, path.relative(installedSkill, installed));
+      const info = fs.lstatSync(installed);
+      assert(!info.isSymbolicLink(), 'Installed guidance must contain real assets');
+      assert(fs.existsSync(selected) && !fs.lstatSync(selected).isSymbolicLink(), 'Copied skill is stale; missing or linked asset');
+      if (info.isDirectory()) compareAssets(installed);
+      else assert(fs.readFileSync(installed).equals(fs.readFileSync(selected)), 'Copied skill is stale; refresh the complete folder');
+    }
+  }
+  compareAssets(installedSkill);
+}
 console.log(JSON.stringify({ package: manifest.name, version: manifest.version, root, skill: selectedSkill }, null, 2));
 JS
 ```
@@ -43,9 +58,11 @@ finder reports its own metadata version; it does not inspect the app installatio
 
 To check a copied skill, set `THEMELIA_SKILL_DIR` to its complete directory when
 running the recipe. The comparison checks metadata contents as well as version,
-so stale copies with the same development version are caught. A successful check
-does not compare every prose file: recopy the complete folder after package
-upgrades or guidance updates, and read declarations from the installed package.
+so stale copies with the same development version are caught. Every installed
+guidance/script/example asset is also compared byte-for-byte; extra app-owned
+files or publisher markers in the copy are not checked. Keep local product policy
+outside the package guidance. Recopy the complete folder after upgrades, and
+read declarations from the installed package.
 
 ## Manual skill copying
 

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

@@ -18,6 +18,20 @@ Load intentional, scoped app overrides after the package stylesheet. Keep broad
 
 UIProvider supplies stable mount-time defaults: explicit prop, provider default, fallback. Per-mount requests/data/callbacks stay on components. ThemeScope from themelia-react-ui/ui-provider places descendant portals inside its CSS boundary. A styled div does not relocate body portals; explicit Base UI portal containers take precedence.
 
+For separated card regions, configure the single application provider with
+`card: { defaultSurface: 'card', defaultHeaderDivider: true, defaultFooterDivider: true }`.
+Explicit Card booleans, including false, override these defaults. Ordinary card
+padding remains md, independent of density. The typed [workspace recipe](../examples/app-layout.tsx)
+exports `workspaceUIDefaults` for that root configuration and composes the public
+workspace/user controls. It does not mount another UIProvider inside the app.
+
+Page owns inline/block insets and offers `narrow` for a centered resource page.
+PageViewport owns scroll containment only. Check actual padding before passing
+`gutter="none"`; a local guide claiming all shell viewports are padded contradicts
+the installed contract. Fix that app policy through its own review rather than
+compensating with card or field padding. Bounded AppSidebar instances use h-full
+inside the shell's constrained column; standalone sidebars may use viewport height.
+
 For RTL, pair the native DOM direction with `DirectionProvider` from the same
 entrypoint. Native `dir` owns text flow and logical CSS geometry; the provider
 owns Base UI keyboard navigation and popup positioning. It does not set `dir`.
@@ -54,4 +68,16 @@ Server code imports pure helpers from `themelia-react-ui/features/email-composer
 
 Maintainer enforcement uses @shadcn/lint through Oxlint plus AST/contract checks. These are not runtime dependencies or a published consumer audit CLI. Configure app lint using published utilities/imports; do not copy repository migration-debt allowances. There is no Sass/SASSC pipeline in this Tailwind package.
 
+For opt-in import/anatomy checks, the package now includes a read-only Node script
+using the app's TypeScript dev dependency; see [review and checks](review.md).
+It is not a global CLI or a complete visual auditor. Keep product policies and
+current adapter/page examples in an app-owned reference, separate from this skill.
+
 The maintainer installed-tarball harness proves the basic provider/control/overlay SSR and hydration fixture, pure email preparation without editor peers, controlled table and email-composer workflows, and optional client module initialization. It checks hydration diagnostics and real callbacks in light/dark at narrow/wide widths. Optional module initialization alone does not prove its complete workflow or server-rendering support; verify the features your app uses. `check:all` runs the serial package and curated browser gates; evidence collection is a separate `collect:browser` command. Both are repository maintainer commands, not installed consumer CLIs.
+
+The scoped directory fixture also runs the packaged recipe's query/clear,
+fixed-scope, loading/error/retry, empty and keyboard row-menu callbacks. It checks
+both container content edges without global preflight; Container and DataTable
+own border-box sizing. Stabilize lifecycle inputs as explained in
+[workflows](workflows.md#scoped-directory). These are example/runtime proofs,
+not evidence of an independent agent choosing the same composition.