themelia-react-ui 1.0.1 → 2.0.0

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

@@ -0,0 +1,70 @@
+# Metrics and statistics
+
+Use this reference for dashboard KPIs, revenue overviews, statistic cards and
+usage summaries. The finder returns exact owners, relevant symbols and recipe
+reads; declarations establish the current props. These components present
+application data and never fetch or define a business metric.
+
+## Select the subject owner
+
+| Subject | Public owner | Frame and lifecycle |
+| --- | --- | --- |
+| One KPI with value, trend or sparkline | `Metric` from `themelia-react-ui/blocks/analytics` | `variant="card"` owns its Card; default/compact/minimal support lower-level composition. Has loading/error presentation. |
+| Peer dashboard KPIs or revenue figures | `MetricGrid` from `themelia-react-ui/blocks/analytics` | Defaults to card metrics; owns gaps and columns responding to its parent. `columns` is a maximum. Has loading, while error/retry/empty remain app-owned. |
+| Metrics sharing one strip and period action | `MetricBar` from `themelia-react-ui/blocks/analytics` | One strip from `MetricData[]`; period callback requests the current period value. App owns choosing/fetching periods and request states. |
+| Current versus previous metric | `MetricComparison` from `themelia-react-ui/blocks/analytics` | Uses current/previous `MetricData`; app defines the comparison baseline. |
+| Used/limit quotas with shares, daily values and period selection | `UsageCard` from `themelia-react-ui/blocks/analytics/usage-card` | Owns a Card and ready/loading/error/empty presentation with retry/period callbacks. No optional chart peer. |
+| One plain label/value fact | `InlineStat` from `themelia-react-ui/blocks/data-display` | Card-free; app chooses whether this subject needs a Card. |
+| Several facts about one record | `MetadataList` from `themelia-react-ui/blocks/data-display` | Card-free; value primitives own formatting. |
+| Caller-owned chart series | `ChartCard` from `themelia-react-ui/blocks/analytics` | Card-free chart composition; caller supplies chart content and an optional Card boundary. |
+
+Start with these subject owners before constructing a Card with a number and
+supporting text. Reuse their formatting, hierarchy and relevant states when
+the contract fits. A custom Card remains appropriate for a distinct subject
+or task with content/coordination these owners do not represent; keep their
+supported lower owners where useful. Do not put another Card around an owner
+that already renders its own surface.
+
+## Dashboard and revenue data
+
+[Analytics recipe](../examples/analytics.tsx) exports `RevenueOverview`,
+`RevenueMetric` and `PlainStatistic`. The overview accepts discriminated request
+state: loading renders MetricGrid skeletons, error replaces data with retry,
+and a ready empty array renders EmptyState. The parent supplies labels/IDs for
+loading metrics, accepts server data, executes retry and ignores stale results.
+It adds no implicit Card around the grid. The other exports show a standalone
+Metric and a plain factual InlineStat.
+
+`MetricData` requires stable `id`, `label` and `value`. Numeric currency values
+use `valueType="currency"` plus `currency`; pass major currency units, rather
+than a Money primitive's `unit="minor"` contract. Percentage values follow the
+shared formatter's ratio contract (0.12 renders 12%). `null` is unavailable;
+zero is real data. A string is already display data. `change.value` is caller
+copy, `change.direction` describes movement, and `trend` can override whether
+movement is positive, negative or neutral. A decline in churn can be positive.
+Keep the selected period and baseline clear in application context.
+
+`MetricGrid` forwards one `variant`, size and state recipe to its peers. Its
+default `gap="xl"` and Card insets remain independent from text/media `size`.
+Narrow parents reduce track count even on a wide viewport. Use `columns` and
+the public variants rather than overriding its internal grid, Card padding,
+value typography or sparkline geometry.
+
+The analytics family declaration/runtime graph requires the optional `recharts`
+peer even when a selected presentation hides its sparkline. Read the finder
+result's peers and installed declarations. UsageCard has a focused leaf import;
+its quota model differs from general MetricData.
+
+## Usage, facts and verification
+
+For `UsageCard` period/loading/error/retry and quota meaning, read
+[usage workflow](workflows.md#task-summaries-usage-and-inline-editing) and its
+[workspace summary recipe](../examples/planning-usage-edit.tsx).
+For record facts, choose MetadataList and primitives through the
+[detail recipe](../examples/detail.tsx), then decide Page and Card boundaries
+using [composition](composition.md#compose-from-the-task).
+
+Verify zero/unavailable values, loading/error/retry/empty, accepted period data,
+long labels/amounts, narrow parent widths and light/dark surfaces. Run the app's
+types and behavior checks; discovery and typechecking do not prove rendered
+geometry, keyboard callbacks or business-data correctness.

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

@@ -30,6 +30,7 @@ a detail workspace or a form; they need different information hierarchies.
 | 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
@@ -53,11 +54,26 @@ 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.
+Commands need explicit importance as well as scope. Describe page commands by
+role in Page's header: `primaryAction` is the route's one main command, and
+`secondaryActions` lists supporting commands in priority order. The header owns
+their treatment: a solid primary button, outline secondary buttons, and a More
+actions menu for overflow, destructive commands and narrow screens. Choosing which
+command is primary, which are `destructive`, and which are `visible` remains an
+application decision; confirm destructive commands in their handler. Use
+`actions` only for non-command controls such as a period select. A back link,
+export and destructive command should not all inherit the same visual emphasis.
+
+```tsx
+<Page header={{
+  title: 'Contacts',
+  primaryAction: { label: 'New contact', icon: Plus, onClick: onCreate },
+  secondaryActions: [
+    { label: 'Export', onClick: onExport },
+    { label: 'Delete list', destructive: true, onClick: confirmDelete },
+  ],
+}}>{/* route content */}</Page>
+```
 
 | Drift | Better decision |
 | --- | --- |
@@ -74,6 +90,48 @@ 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.
+
+For rows, grids, main/aside regions and matching peer gaps, use the
+[layout-owner map](#structure-and-spacing).
+
+### Headed blocks inside surfaces
+
+AddressCard, PaymentMethod, SeoListingCard and ProductVariantsManager accept
+Card's `surface`, `padding` and `headerDivider` props. Use `surface="card"` when
+that owner is the framed subject; it supplies the header and aligned body insets
+and inherits provider dividers. Do not add an untitled padded Card around it.
+Omit surface for an unframed embedded subject; its header rule defaults off.
+An explicit divider still wins. ProductVariantsManager also forwards
+`footerDivider` for its footer slot. Separate reusable body content can still be
+composed in a caller-owned Card; choose one owner for each headed boundary.
+
+## 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
@@ -101,24 +159,108 @@ 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. A Card title needs no icon;
+pass `icon={<Icon />}` only when the glyph carries meaning (state, a brand, a type
+users scan for), never as raw SVG in title JSX. Custom titles remain appropriate
+for richer content. Facts and rows follow the same rule: one glyph repeated on
+every MetadataList item or Item row is decoration, so leave `icon`/media empty.
+
 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.
+Dividers are off by default and
+should stay off: separate a card's sections with `contentGap` or a Stack gap
+clearly larger than the row gap (`2xl` between sections). UIProvider can configure
+`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.
 
 ## Structure and spacing
 
-Shells own gutters, surfaces own padding, sections own rhythm, Stack/Grid own sibling gaps, typography owns none. Prefer gap/padding/size props to local appearance overrides.
+Choose the smallest owner that describes the region. These layout blocks are
+published primitives and layouts, not the domain compositions under `blocks/*`.
 
-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.
+| Responsibility | Exact family and owner | Contract to preserve |
+| --- | --- | --- |
+| Vertical siblings or an action row | `base/structure`: Stack | Vertical by default; `direction="horizontal"` creates a row and wraps by default. Default gap is `md` (8px). There is no separate Row export. |
+| Known responsive tracks | `base/structure`: Grid | Scalar columns are literal; use `columns={{base:1,lg:3}}` for breakpoints. Omitted columns use one, then two from md. Default gap is `xl` (16px). |
+| Track spans | `base/structure`: GridCell | Use `span={{base:1,lg:2}}` inside the nearest Grid; keep meaningful DOM order. |
+| Equal tiles that fit their parent | `base/structure`: AdaptiveGrid | Select `minColumnWidth`; tracks follow available width. Use Grid for prescribed breakpoints or TwoColumnLayout for a supporting rail. |
+| Centered measure and inline gutters | `layout/containers`: Container | Defaults to xl measure and md gutter. Owns no vertical inset, scrolling or surface chrome. |
+| A semantic content section | `layout/containers`: Section | Owns sibling rhythm, default `xl`; it adds no Card frame or page gutter. |
+| Main content with a supporting rail | `layout/containers`: TwoColumnLayout | Owns header/main/aside/footer order and `2xl` gaps (24px). Main/aside contents choose their own Stack gaps. Page rhythm (header to body, major Sections) uses `3xl` (32px). |
+| A bounded page scroll region | `layout/containers`: PageViewport | Owns scrolling and query containment, with no padding. AppLayout already supplies one. |
+| Route title, commands and page content | `layout/page`: Page | Owns measure, inline/block gutters and header/body rhythm. Use `narrow` for a focused resource. |
+| Application header/sidebar chrome | `layout/app-shell`: AppLayout | Select the shell variant, compose slots and router callbacks, and let its viewport contain Page. |
+| A framed subject | `base/cards`: Card | Owns surface padding, header/body/footer alignment and separators; layout blocks own the space between Cards. |
+
+See the typed [layout-block composition](../examples/layout-blocks.tsx) when composing these owners.
+
+Use these public structures for repeated passive composition rather than
+rebuilding the same flex/grid spacing on divs. Tailwind remains appropriate for
+positioning, overflow, chart/table geometry and custom intrinsic tracks. Structure
+preserves child identity; it does not inspect, clone, reorder or frame children.
+
+### Main and aside Card gaps
+
+Peer Cards in a Page/TwoColumnLayout workspace use `gap="2xl"` on both main and
+aside Stacks to match its 24px grid gap. Give a peer Grid the same gap when it
+belongs to that rhythm. A compact local card grid may deliberately keep Grid's
+16px default. Stack's 8px default is general sibling spacing, not an automatic
+Card rhythm; choose the role explicitly. Values above use shipped roots and
+scale through the existing space-scale contract.
+
+The [region recipe](../examples/layout-blocks.tsx) keeps both inner Stacks on that same peer gap.
+
+Use `textGap="normal"|"dense"` for title/description copy; keep action gaps,
+form groups, peer regions and surface insets independent. Do not use small copy
+gaps between independent Cards or shrink Card padding to match control density.
+Framed Card rings extend outside layout rectangles: inspect visible clearance
+in both axes as well as computed gaps.
+
+### Horizontal rows
+
+See the typed [layout-block composition](../examples/layout-blocks.tsx): Page
+supplies its boundary, TwoColumnLayout splits the regions, inner Stacks share
+peer rhythm, and a horizontal Stack wraps footer actions. The app supplies the
+subjects and commands. For viewport-responsive columns use Grid; for available
+parent width use AdaptiveGrid or `TwoColumnLayout adaptTo="container"`.
+
+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
 
@@ -132,6 +274,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.
@@ -150,8 +299,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.
@@ -257,6 +406,43 @@ 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 |

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

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

@@ -14,11 +14,22 @@ 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.
 
@@ -35,13 +46,77 @@ 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.
 
-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.
+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.
+Deprecated migration names such as `SmartCard` or `ContentBlockProps` never
+appear in intent recommendations. When a result touches one, its `deprecated`
+map names the replacement, for example `{ "SmartCard": "Use Card." }`; write
+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.
+
+`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.
 

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

@@ -64,6 +64,28 @@ files or publisher markers in the copy are not checked. Keep local product polic
 outside the package guidance. Recopy the complete folder after upgrades, and
 read declarations from the installed package.
 
+## Upgrading to the neutral button default
+
+An untoned `Button` is now the neutral outline (`tone="secondary"`,
+`buttonStyle="outline"`); a Button with a `tone` and no `buttonStyle` stays
+solid. Screens that relied on untoned Buttons being the solid primary can keep
+their look with the bundled codemod. It reports by default and edits only with
+`--write`; review the diff before committing:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/pin-button-defaults.mjs src
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/pin-button-defaults.mjs --write src
+```
+
+It adds `tone="primary"` to every Button, BaseButton or BaseButtonLink imported
+from the package without a `tone`. Add `--solid-only` to skip untoned outline
+and ghost Buttons so they turn neutral instead of keeping the brand color.
+Buttons whose props come from a spread are listed as `unresolved` for review.
+Apps that already set `UIProvider` `button.defaultTone` keep that tone and do not
+need the codemod; `button: { defaultTone: 'primary', defaultButtonStyle: 'solid' }`
+restores the previous default app-wide. Afterwards, demote extra primaries so
+each page or surface keeps one.
+
 ## Manual skill copying
 
 1. Choose an agent skill destination in the user's configured skills directory,

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`.
@@ -36,7 +50,38 @@ does not replace the single mount-time UIProvider configuration boundary.
 
 Routing comes through href, callbacks or Base UI render composition. React Router is not required. Component chunks preserve client boundaries; pure utilities remain separate.
 
-Use ActionDialog, ActionDrawer, ConfirmDialog and useOverlayVisibility from features/overlays. Pass overlayProps for visibility. onAsyncConfirm awaits the operation; onError reports failure. Do not also pass onConfirm, which takes precedence. Sheet is structural infrastructure, not another workflow API.
+## Dialogs, confirmations and drawers
+
+Every dialog-like surface comes from `themelia-react-ui/features/overlays`; it is
+the only modal system. The overlay owners hold focus entry and trapping, Escape
+and outside-click dismissal, focus return to the trigger, pending and error
+states, portal theming and the shared scrim (a plain tint, never a blur).
+
+| Need | Owner |
+| --- | --- |
+| A focused edit or form with confirm/cancel | `ActionDialog` |
+| A yes/no question, or a destructive confirmation | `ConfirmDialog` (destructive tone for irreversible actions) |
+| A longer form, filters or record details beside the page | `ActionDrawer` |
+| Open state, triggers and several overlays on one screen | `useOverlayVisibility` (`overlayProps`, `show`, `hide`) |
+
+Pass `overlayProps` for visibility. `onAsyncConfirm` awaits the operation and
+keeps the overlay open on failure; `onError` reports it. Do not also pass
+`onConfirm`, which takes precedence. Each overlay owns one primary command, its
+confirm button; compose the body with the ordinary Stack, FormField and Card
+anatomy and leave its insets to the overlay.
+
+Do not hand-roll a modal (a `fixed inset-0` scrim, `role="dialog"`,
+`aria-modal`), do not import the lower-level `Dialog`, `AlertDialog` or `Sheet`
+building blocks, and do not add another modal library (Radix Dialog,
+react-modal, vaul, Headless UI or React Aria dialogs). The optional checker
+warns on each of these. Popovers, menus, selects and tooltips are anchored
+surfaces, not dialogs: use their own owners.
+
+To show a table full screen, use `DataTable`'s own mode (`fullscreen` or
+`defaultFullscreen`, `onFullscreenChange`, `showFullscreenToggle`) instead of
+moving the table into a dialog. It maximises the table in place, so scroll
+position, focus and column state survive; Escape leaves, Tab stays inside and
+focus returns to the toggle.
 
 PlaceAutocomplete from themelia-react-ui/features/map uses Photon by default. Supply a stable or useCallback-memoized searchPlaces: PlaceSearchCallback to use your geocoder; it receives PlaceSearchOptions and an AbortSignal and returns Promise<PlaceFeature[]>. Adapt provider results to the existing place shape and OSM identifiers (duplicates are removed by osm_id). Changing provider identity or search options cancels the old lookup and searches the current query. Respect the signal; superseded responses are ignored even if a provider cannot cancel. Keep provider identity stable during ordinary renders. Notification callbacks may be inline. onSearchError reports current failures; the built-in Retry action repeats the lookup and strings.retry localizes its label.