themelia-react-ui 1.0.1 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,422 @@
 # Changelog
 
+## 2.0.0 — 2026-10-16
+
+A major release. Untouched defaults now give a screen one deliberate primary
+command, neutral surfaces where colour only states status, and the overlay
+family for every dialog-like surface. Public exports and props are retained (the
+contract check keeps every public symbol); what changes is defaults, appearance,
+a few DOM hooks and some semantics.
+
+### Upgrading from 1.x
+
+- **Buttons.** An untoned `Button` is the neutral outline. Give each screen's
+  main command `tone="primary"`, run
+  `docs/consumer-skill/scripts/pin-button-defaults.mjs` (dry run by default,
+  `--write` to apply) to keep existing screens' look, or restore the old default
+  app-wide with `UIProvider` `button: { defaultTone: 'primary',
+  defaultButtonStyle: 'solid' }`.
+- **Brand colour.** The default primary is near-black. Import
+  `themelia-react-ui/themes/green.css` after `style.css` to keep the green brand.
+- **Badges.** An untoned `Badge` is neutral; `UIProvider`
+  `badge.defaultTone: 'primary'` restores the old default.
+- **Page titles** are the route's `h1` at 20px; pass `headingTag="h2"` for a page
+  nested inside another titled page.
+- **Overlays.** Replace the deprecated base `Sheet` exports with `ActionDrawer`
+  from `features/overlays`. `ConfirmDialog` shows its tone icon only with
+  `showIcon`. Scrims no longer blur, and dialog regions draw no header or footer
+  rules.
+- **Formatted text.** Negative numbers print with a true minus (U+2212) instead
+  of a hyphen; update tests, snapshots or parsers that match formatted output.
+- **Decorative icons and dividers** are gone from the library's own blocks,
+  features and templates. Public `icon`/media props and Card `headerDivider`/
+  `footerDivider` remain for products that need them; `adminStarterUIDefaults`
+  no longer turns card dividers on.
+- **DOM hooks.** `InventorySectionCard` exposes card hooks instead of
+  `content-block--*`, and `seo-listing-card--score-icon` is removed.
+
+### Changes
+
+- **Breaking (visual): overlays have no blur and no static rules, and they are
+  the only dialog API.** The modal scrim is a plain `--overlay-backdrop` tint.
+  Dialog, alert-dialog and drawer regions draw no header/footer rules or tinted
+  footer: the shell owns a 20px outer inset and 16px between regions, and a
+  scrolling body shows a rule only on an edge that hides content. Surfaces use
+  one border on `bg-popover`; drawers draw one rule on their open edge. The
+  close button is centred on the first title line and comes last in the DOM, so
+  opening focuses the first field or action. `ConfirmDialog` matches
+  `ActionDialog` widths, supports `surfaceStyle` and shows no tone icon unless
+  `showIcon`; emphasis no longer tints the border; a non-modal `ActionDrawer`
+  stays open on page presses; `initialFocusRef` accepts nullable React 19 refs;
+  a string `trigger` renders a Button. The base `Sheet` exports are deprecated
+  in favour of `ActionDrawer`. DataTable's in-place `fullscreen` mode stays the
+  one modal surface outside the overlays: the table's own region is maximised,
+  so its scroll position, focus and column state survive, and the contract
+  check (`modal-owner`) rejects any other hand-built modal or borrowed
+  Dialog/Sheet in library source. The consumer skill (house rule 9 and a dialogs
+  section) and the checker (`raw-overlay-primitive` for `role="dialog"`,
+  `aria-modal`, `fixed inset-0` layers and modal libraries; `deprecated-owner`
+  from the public index) enforce the overlay owners. Nothing in the library uses
+  `backdrop-filter` any more: sticky table headers and toolbars, the form
+  actions bar, carousel controls and upload overlays are opaque.
+- **Inline values follow running text.** Inside `Text`, `Heading`, `Label`,
+  `TextLink`, `ItemTitle`/`ItemDescription` and `CardDescription`, value
+  primitives (`Value`, `MonoValue`, `Money`, `Number`, `Percent`, `Duration`,
+  `FileSize`, `Dimensions`, dates, links) take the sentence's size, colour,
+  weight and leading unless a prop says otherwise; standalone use is unchanged.
+  `Initials` inherits by default. Text `type`/`weight`/`lineHeight` accept
+  `'inherit'`. Empty values share the `EmptyValue` treatment.
+- Negative numbers print with a true minus (U+2212) in every formatter and
+  number primitive (`formatWithMinusSign` in `lib/format`).
+- Form controls share one geometry and state contract: every field and
+  field-shaped trigger is the same height, radius, `--input` border, text size
+  (16px on touch) and 2px focus ring; a keyboard-focused invalid field shows a
+  full-strength destructive ring; select-like chevrons share
+  `selectToggleRecipes` (16px glyph centred where the Select draws it);
+  Textarea's first line aligns with an Input's text; field triggers no longer
+  take a button hover fill; disabled inputs lose the read-only fill. Checkbox
+  shows a dash when indeterminate; choice cards mark selection with the border
+  only; pill radios get roving arrow-key focus; DecimalInput steps with arrow
+  keys and keeps uncontrolled values; DatePicker gains `id`/`invalid` and no
+  longer reddens its label; DateTimeInput passes `stepMinutes` correctly;
+  Cascader gets an inline clear; Combobox Escape on a closed field keeps the
+  value and reaches the surrounding overlay. A Combobox reserves its whole
+  toggle (and clear) target plus the copy gap, so a long value never runs under
+  a target at any density. A one-line text button is exactly its action height
+  at every spacing and density (its block inset is capped); wrapped labels
+  still grow the button.
+- Display and navigation: Badge follows its parent's alignment (no
+  `self-center`); flat/`padding="none"` Cards use the 16px header-to-body gap;
+  the default outline button border is visible in dark; `TextButton` md is
+  `text-sm`; ButtonGroup seams and corners are fixed; untoned ActionButtons are
+  neutral; menu group captions use the xs secondary role; OverflowTabBar gets
+  arrow/Home/End keys and the shared 36px recipe; active tabs read above the
+  track in dark; pagination links are 36px squares; accordion focus is inset
+  with no open tint; toaster status icons reach 5:1; code diffs use tints;
+  StackedAvatars fallbacks are neutral; tables render rules without preflight
+  and are a tab stop only while they overflow. `PageHeading` `withSeparator`
+  defaults to `false`.
+- Typography: Heading `tracking-tight` from xl and `leading-tight` from 2xl;
+  link focus rings hug the text and follow wrapped lines; text, headings and
+  money align with logical start/end so they mirror in RTL.
+- Scoped density: arbitrary values no longer read derived `--spacing-*` aliases
+  (resolved once on `:root`), so tracks, insets and offsets follow a
+  `data-density` scope.
+
+- **Breaking (visual): visual restraint pass.** Icons now carry information
+  or are omitted, colour only states status, and spacing, not rules, separates
+  sections. Public `icon`/media props remain for consumers; the library's own
+  compositions stop passing decorative ones.
+  - Rows: a plain `Item` (default variant, no inline padding) in an `ItemGroup`
+    sits flush with the group's top and bottom edges, plain rows touch so their
+    density padding is the row spacing, and the default variant drops its
+    transparent 1px border so row text aligns with headings and labels above
+    it. Boxed `outline`/`muted` rows keep their gap. This fixes uneven space
+    around dividers and at card bottoms (8px above a rule against 17px below
+    it, 30px at a card's bottom against 20px at its top on the order page).
+  - Blocks and features no longer hard-code decorative icons on card titles
+    (address, payment method, order/refund status, tax breakdown, subscription,
+    voucher, coupon, cart, inventory, SEO listing, every product section, sensitive
+    actions, AI confirmation/tool call/package info/citation), on metadata and
+    list rows, inside inputs and badges, or on ordinary text buttons. Kept:
+    icon-only buttons, menu and navigation icons, affordances, search glyphs,
+    `+` on add commands, state glyphs, event-type markers and real media.
+  - Colour states status: kinds, categories and counts are neutral; live and
+    in-progress states use `info` instead of the near-black primary;
+    `LoyaltyPoints` `tierTone` defaults to `neutral` (was `warning`); activity
+    events without a status tone are neutral; product rows render
+    `tone="primary"` neutral; micro-grid single-series charts use `--chart-1`.
+  - No boxes inside cards and no section rules: tinted or bordered inset panels,
+    stat tiles and per-section dividers are gone across commerce, data-display,
+    AI, admin, product, activity, resource-assignment, schema-form, sync and
+    media-library compositions. One rule stays above financial grand totals.
+    Status chips sit beside their title (`titleSuffix`).
+  - Amounts and dates use the UI font with tabular figures; monospace stays for
+    identifiers and codes.
+  - Sentence-case default strings across commerce, admin, AI and dense-info
+    blocks (for example `Refund status`, `Tax breakdown`, `Redeem points`,
+    `View details`, `Edit role`, `Next step`). `DenseInfoStrings` gains an
+    optional `priority`.
+  - `ActivityLog` shows a category chip only when an entry passes `label` (it no
+    longer falls back to the raw `kind`), and date groups read `Yesterday` and
+    `October 14, 2026` instead of uppercase eyebrows with ordinals.
+  - `DateCell` and `DateMetaCell` `showIcon` default to `false`;
+    `GlobalSearchIdleState` headings have no default icons; `PageHeader` has no
+    separator after the back button; `AppSidebar` groups are separated by space
+    instead of rules; navigation count badges stay neutral when active.
+  - `OrderStatus` drops the facts that repeated its badge and timeline;
+    `LoyaltyPoints` shows Redeem only with `onRedeem`; vouchers show a balance
+    only when one is given; `InventorySectionCard` renders through `Card`, so its
+    `content-block--*` hooks become card hooks, and `seo-listing-card--score-icon`
+    is removed.
+  - Base fixes: `ActionMenu`'s icon-only trigger follows `buttonProps.size`;
+    Card `contentTop`/`contentBottom` share the content gap (`lg`, or
+    `contentGap`) instead of touching the body.
+  - Templates: `adminStarterUIDefaults` no longer turns on card header/footer
+    dividers; facts, line items, KPIs and commands lose decorative icons;
+    count/kind badges, repeated identity rows and repeated facts are removed.
+  - Guidance: house rule 7 and the Card anatomy reference cover decorative
+    icons and dividers; the composition checker warns (`decorative-icon`) on a
+    Card title icon or an icon on more than one MetadataList fact; AGENTS.md
+    records the visual restraint rules.
+
+- **Breaking (visual): an untoned Button is now the neutral outline**
+  (`tone="secondary"`, `buttonStyle="outline"`), so a screen gets one deliberate
+  primary instead of a primary on every button. Give the main command
+  `tone="primary"`. A Button with a `tone` and no `buttonStyle` is now always
+  solid: `UIProvider` `button.defaultButtonStyle` applies only to buttons without
+  a tone. Run `docs/consumer-skill/scripts/pin-button-defaults.mjs` (dry run by
+  default, `--write` to apply, `--solid-only` to let untoned outline and ghost
+  buttons turn neutral) to keep existing screens' look, or restore the previous
+  default app-wide with `button: { defaultTone: 'primary', defaultButtonStyle:
+  'solid' }`. The library's own components keep their primary commands
+  explicitly; their untoned outline and ghost buttons (cascader, signature pad,
+  questionnaire navigation) are now neutral instead of brand-colored, and
+  `SubmitStateButton` keeps the primary role for submit.
+- Add a 32px `3xl` structural gap step (`gap-space-3xl`, `gap-x-space-3xl`,
+  `gap-y-space-3xl`; `--spacing-space-3xl` scales with `--space-scale`) for page
+  rhythm. Page now separates its header from its body with `3xl` (was 24px), and
+  Stack/Grid/Section accept `gap="3xl"` between major sections. The utility
+  budget grows from 393 to 396 spellings for this one shared responsibility.
+- **Breaking (visual): the default primary is neutral.** `--primary` is
+  near-black in light (`oklch(0.205 0 0)`) and near-white in dark, so the brand
+  no longer sits next to the success green (they were ΔE_OK 0.074 apart). The
+  previous green is the opt-in brand theme `themelia-react-ui/themes/green.css`:
+  import it after `style.css` to keep the old look. It sets primary, its
+  foreground, the dark primary accent and the first chart series, and passes
+  the same contrast contract. `--primary-accent` now follows `--primary` in
+  dark too.
+- Form-control boundaries reach 3:1 contrast (WCAG 1.4.11): `--input` is
+  `oklch(0.62 0 0)` in light (was the divider color, 1.26:1) and white at 40% in
+  dark (was 15%), so inputs, selects, checkboxes, radios and switch tracks are
+  visible on every surface. `--border` stays the lighter divider color. The
+  contrast contract now checks `--input` at 3:1 on background, card, popover,
+  muted, accent and secondary surfaces. The repeater's empty placeholder uses
+  the divider border.
+- Button labels wrap inside the available width instead of overflowing: the
+  action height is now a minimum for text buttons (icon-only buttons stay fixed
+  squares), and buttons cap at their container's width. Pass `truncate` to keep
+  one line with an ellipsis where a button cannot grow, such as a joined group
+  or dense toolbar. Components that size a button themselves (`h-auto`,
+  `h-full`) now also reset the minimum height, and the header search trigger
+  uses `size="sm"` instead of a height override.
+- Add role-based page commands to PageHeader and `Page header`:
+  `primaryAction` (one solid primary command, trailing and always visible) and
+  ordered `secondaryActions` (two outline buttons, then a More actions menu).
+  Destructive secondary commands always move into that menu; below `sm` every
+  secondary command collapses into it through CSS. Commands carry no tone or
+  button style. `moreActionsLabel` names the menu; the new `PageHeaderAction`
+  type is exported from `layout/page` and `layout`. Existing `actions` and
+  `slots.actions` are unchanged: `actions` renders before the commands, and
+  `slots.actions` still replaces the whole region.
+- Move the admin templates, consumer recipes and Page catalogue examples to the
+  role-based commands. Header buttons now share one size, and the stacked shell
+  recipe no longer repeats the page's Create record command in its navigation.
+- The optional consumer checker warns (`page-command-roles`) when Page or
+  PageHeader `actions` hold command buttons, pointing to `primaryAction` and
+  `secondaryActions`. The analytics template's period filter is now a labelled
+  Select instead of a toggle button.
+- Nested `UIProvider`s no longer throw. A nested provider inherits the nearest
+  provider's resolved defaults and overrides only the keys it sets, so
+  `AdminUIThemeProvider` works inside an application's root provider.
+- Metric surfaces format currency, numbers and percentages with the same
+  formatter and UIProvider policy as `Money` (locale, default currency and
+  `formatMode`). A currency metric without a currency now uses the provider
+  default (`USD` by default) instead of EUR, and prints like Money
+  (`1,840.00 USD` by default) instead of `USD 1,840.00`. `formatMetricValue`
+  accepts optional `FormatMetricValueOptions`.
+- Add `useMoneyFormatter()` to `primitives` for money in strings (labels,
+  toasts, activity text) with the Money rules; the templates use it instead of
+  hand-built `$x.xx USD` strings, and their tables use the Date primitive.
+- `toTableAction` keeps running actions disabled and hidden actions hidden in
+  DataTable rows; `toMenuAction` carries `id`, `visible` and `group`.
+- Themes declare `color-scheme`, so native scrollbars and form controls follow
+  dark mode. Light `--primary-accent` now follows `--primary`, so a rebrand
+  needs one root.
+- Unit tests resolve the package's own imports from source, so `npm test` no
+  longer needs (or silently uses) a previous build.
+- Page titles are the route's `h1` by default (was `h3`) and use the 20px
+  `text-xl` role (was 18px), so page and card titles (16px) read as distinct
+  levels. Pass `headingTag="h2"` for a page nested inside another titled page.
+- Card and MediaLibrary plain-text titles are exposed as level-2 headings, so
+  assistive technology can move between surfaces. Title-suffix badges stay out
+  of the heading's name; custom title nodes keep their own semantics.
+- An untoned Badge is now neutral (was primary), so only a deliberate tone
+  signals state. Set `UIProvider` `badge.defaultTone: 'primary'` to keep the
+  previous look. The Default address and payment-method badges are neutral too.
+- `useMoneyFormatter(defaults)` binds screen defaults such as `currency` once;
+  each call can still override them. `MoneyFormatterOptions` is exported.
+- The consumer skill opens with eight house rules (provider, Page, command
+  roles, Stack/Grid, typography and value primitives, semantic color, neutral
+  badges, Card slots). The checker adds review warnings for raw palette color
+  classes, native `<button>` and `<h1>`–`<h6>` elements, and pages with more
+  than one solid primary command. The orders and staff templates now have one
+  primary command each.
+- The consumer skill's public index lists each family's deprecated names with
+  their replacements (`SmartCard`: "Use Card.", `SmartCardProps`: "Use
+  CardProps."), derived from `@deprecated` JSDoc. The finder leaves them out of
+  task recommendations and flags them when a query names one.
+- Event calendar markers in narrow day cells keep the compact action height
+  (28px), so they meet the WCAG 2.2 24px target size instead of a 12px sliver.
+- Regenerate `package-lock.json`: it pinned lightningcss 1.32.0 where the
+  package and Vite require `^1.33.0`, so `npm ci`, and with it CI, failed
+  before running any check.
+
+## 1.0.3 — 2026-10-15
+
+- Document layout-block ownership, horizontal Stack rows, responsive tracks and
+  parent adaptation; ship a typed region-composition recipe and route common
+  layout queries to the corresponding owners and focused guidance.
+
+- Align template peer Card stacks with Page/TwoColumnLayout’s existing `2xl`
+  rhythm: 24px in both axes at default scale, including stacked mobile regions.
+
+- Let AddressCard, PaymentMethod, SeoListingCard and ProductVariantsManager own
+  their framed Card anatomy through existing surface/padding/divider props.
+  Preserve unframed defaults and suppress inherited embedded header rules;
+  replace redundant template wrappers with one full-width Card boundary.
+- Audit the admin templates: isolate overlay drafts, preserve staff save/discard
+  baselines, close mobile navigation, honor shell presets/density and repair
+  variant duplication/options persistence. Include templates in design lint and
+  installed-package typechecks; correct their documented scope and discovery.
+- Keep long MetadataList row labels from squeezing monetary values out of narrow
+  panels, and use the semantic copy-gap recipe for label/value rhythm.
+
+- Increase the shared surface-x/y defaults to 1.25rem: ordinary Card insets are
+  20px, compact surfaces 10px and large surfaces/page gutters 36px at default
+  scale. Preserve independent row padding, control heights, copy gaps and radii.
+- Keep UsageCard period tabs on the shared scrollable track in narrow cards,
+  preventing wrapped labels from escaping the header into usage figures.
+
+## 1.0.2 — 2026-10-15
+
+- Raise the default outer radius from 8px to 12px. Inputs, buttons, select/facet
+  triggers, collection highlights and navigation rows share a bounded 0.75× inner
+  role (normally 9px), derived from the same public root. The height/density bound
+  prevents short controls becoming capsules under large radius overrides.
+- Enforce outer/inner ownership in repository and optional consumer checks;
+  verify painted corners, focus/selection, scoped portals and independent action/
+  field heights on desktop/mobile in both themes and densities. Preserve bounded
+  image-removal buttons and inner media-list focus targets while Card hit areas
+  retain outer corners.
+- Explain the radius roles throughout consumer/maintainer skills and catalogue
+  guides. Route border-radius, page-padding and Card-anatomy searches to their
+  actual owners, declarations and focused composition references.
+
+- Repair post-remediation findings at shared owners: independent media sizing,
+  complete directional spacing CSS/merge vocabulary, sRGB default colors,
+  dark sunken/sidebar roles, host-colored outline buttons and active feedback.
+- Restore KPI and page-title hierarchy, square heatmap cells and grouped legend,
+  gift-card balances and strip layering. Align table/code/message/image insets
+  with their actual spacing roles and preserve standalone shell/Card fonts.
+- Make calendar events compact and readable, retain mobile Today, portal tag
+  suggestions, and share compact inline actions across filters, products and
+  comments. Date pickers now inherit provider scale and accept an explicit size.
+- Add typed Card region padding, remove caller inset overrides, improve real
+  flagship analytics examples, and strengthen discovery/consumer composition
+  checks with exact imports and practical skill examples.
+- Close .ts recipe, Card-slot and SVG-embedded HTML lint gaps. Add focused
+  desktop/mobile light/dark checks and a finding-by-finding verification ledger.
+- Pair Tooltip shell/arrow with inverse text in both themes. Wrap rich search
+  metadata without clipping currency or duplicating the wide value column.
+- Consolidate corners under the single public shadcn radius root. Anchored
+  borders use the shared semantic boundary.
+
+- Align ordinary controls and menu/command highlights through their shared
+  inner role. Keep compound fields and segmented toolbars within one sized
+  border; preserve provider sizing through filters, search and calendar controls.
+- Tighten shared title/description defaults to normal 4px and dense 2px. Remove
+  typography margins and redundant Card region spacing without adding tokens.
+- Make native inputs, navigation, color pickers, provider links and framed icons
+  own their box sizing independently of consumer resets. Keep search height and
+  keyboard focus stable when clearing; preserve inline collapsed activity metadata.
+- Reject semantic-but-wrong radius/height overrides and copy margins. Route
+  consumer geometry discovery to focused references, and verify installed
+  package geometry across provider sizes, independent scales and both themes.
+
+- Retire the final 87 spacing/control debt expressions through shared row,
+  surface, control and navigation owners; reject restored lint allowances.
+  Preserve fixed chart/illustration geometry with native SVG drawings.
+- Align message continuations to actual media tracks, preserving rich avatar
+  slots, empty states, RTL and focus. Keep compact navigation text readable,
+  selected Item titles theme-aware, and documentation guides logically indented.
+- Keep avatar removal reachable outside image clipping, preserve disabled
+  Sidebar targets through tooltips, retain heatmap civil dates across timezones,
+  and announce localized comment attachment rejection with safe reset/retry.
+- Adapt auth split columns and panel visibility to the shell's own width;
+  keep feature copy shrinkable in narrow parents and scoped themes.
+
+- Repair multiline/BEM class merging and derive property-aware merge namespaces
+  from actual CSS aliases. Verify utility emission alongside generated freshness.
+- Close internal-import, static-template, passive-anatomy and omitted/default-gap
+  lint/checker gaps; improve component discovery without inventing unsupported APIs.
+- Restore Button solid/tonal states, unreset field/list/font ownership, and
+  combined trailing-action geometry. Add concurrency and state-combination regressions.
+- Add an optional Heading visual scale without changing semantic/default sizing;
+  restore prominent KPI values and native Metric navigation/actions.
+- Consolidate table scroll/focus ownership, prioritize calendar titles by available
+  parent width, and review status foreground/elevation roles in both themes.
+- Wire grouped/individual table resizing with real pointer/keyboard sizing,
+  inherited RTL direction and nonoverlapping sticky header rows. Strengthen
+  semantic focus contrast, including native field clear/reveal actions.
+- Follow Slider's actual native input focus and attach the calendar day-button
+  ref, preserving arrow-key focus and visible indicators inside date pickers.
+- Measure both field addon tracks naturally under independent scales; preserve
+  caller padding overrides without adding public theme variables.
+- Add a finding-led drift guide with concrete reproductions, shared-owner
+  repairs, image review and executed behavior checks.
+
+- Page owns larger `lg` inline/block insets, with `padding` and a centered
+  `narrow` resource-page mode; explicit width and gutter choices remain supported.
+  StackedLayout's contained measure owns the same large inline inset once.
+- Page and workspace record headers default to dense supporting-copy rhythm.
+  Standard back controls remain beside the title while wrapped page commands
+  retain the full header width. Workspace content/header/footer share token insets.
+  Workspace regions adapt to parent width; narrow workspaces scroll long headers
+  with their body, while wide regions retain independent main scrolling.
+- Add UIProvider card footer-divider defaults and the matching theme-editor
+  setting, preserving explicit overrides and one empty-body boundary. Ordinary
+  Card padding remains md.
+- AppSidebar adds pinned headerStart/headerEnd slots, uses a separated footer,
+  and inherits compact navigation spacing from LayoutSidebarProvider by default.
+- Enrich shell/account/workspace discovery, ship a complete shell recipe with
+  provider defaults, and add contextual compact-card/page-gutter review warnings.
+  Consumer guidance explicitly distinguishes Page padding from PageViewport scrolling.
+- Card headers wrap by available content space rather than a named-container
+  breakpoint. App shell variants retain their width inside the sidebar provider;
+  UsageCard period headers no longer retain a vertical flex basis after wrapping.
+- Preserve MetadataList primary value size in compact density. Separate framed
+  Card peers in provider/metadata examples and verify visible ring clearance.
+  Document card surface policy, header icon/placement and metadata hierarchy.
+- Route KPI, revenue, statistics and quota discovery to the supported analytics
+  owners. Finder results link relevant symbols, focused references and recipe
+  exports; ship analytics and centered-resource recipes with installed checks.
+- MonthYearPicker uses public Select menus for both nested selectors. Repair
+  confidence-dial centering, narrow table feedback, centered EmptyState copy,
+  floating email dismissal and responsive custom calendar event rendering.
+- MediaLibrary adds titleSuffix and an optional onItemReplace request callback
+  for the inspected asset; unsupported replacement actions remain hidden.
+- Pending overlay confirmations disable generated actions/dismissal and retain
+  modal keyboard focus; rejection restores retry. FormField no longer duplicates
+  a nested control's id onto a passive wrapper. Coupon/voucher previews exercise
+  validation, accepted results and removal through public callbacks.
+- Dialog, confirmation and sheet title/description wrappers reset native margins,
+  keeping shared copy gaps correct without a consuming app's global preflight.
+- Input and Textarea preserve loading when disabled is explicitly false, prevent
+  read-only clear actions, and clear registered/native values as well as form data.
+- HeaderSearch truncates long placeholders within narrow parents; responsive
+  HeaderUserMenu triggers retain the signed-in user's full accessible name.
+  TaskCard retains its disclosure control beside wrapping header content.
+- Add public-website discovery and a typed Container/Section service-page recipe,
+  preserving freedom to compose content without application chrome or KPI anatomy.
+- InventorySection delegates responsive header wrapping to Card, preventing a
+  vertical flex basis from creating a large blank header on narrow screens.
+- Analytics drawing follows live reduced-motion preferences with stable server
+  markup. Metric loading uses the shared Skeleton owner, and micro progress
+  disables its width transition when reduced motion is requested.
+- Item owns border-box sizing, keeping padded Attachment rows inside Message
+  content even when an application has no global CSS reset.
+
 ## 1.0.1 — 2026-10-12
 
 - Consumer guidance now assigns task, scope, information priority and command

package/README.md

@@ -2,7 +2,7 @@
 
 A publishable React UI package built on Base UI and Tailwind, with shadcn-compatible themes and Themelia's public APIs. Routing, persistence, permissions and translations remain consumer-owned.
 
-Package: **`themelia-react-ui`** · current version: **`1.0.1`** · MIT licensed.
+Package: **`themelia-react-ui`** · current version: **`2.0.0`** · MIT licensed.
 The GitHub repository is `themelia-react-ui`; npm imports use `themelia-react-ui`.
 
 Consuming apps start with [consumer setup](#consumer-setup) and the packaged
@@ -15,7 +15,7 @@ Commerce blocks include `Receipt` and `ReceiptItems` from `themelia-react-ui/blo
 
 ## Development
 
-For repository development and verification, use Node 24.12+ within the Node 24 line, or Node 26, and npm. CI pins 24.12.0; local checks ran on 26.3.1. The package consumer engine contract remains `>=22.12.0`, separate from the verification toolchain:
+For repository development and verification, use Node 24.12+ within the Node 24 line, or Node 26, and npm. 24.12.0 is the minimum; local checks ran on 26.3.1. The package consumer engine contract remains `>=22.12.0`, separate from the verification toolchain:
 
 ```sh
 npm ci
@@ -31,6 +31,10 @@ The Vite React playground has foundations, a complete searchable catalogue, and
 
 `check` runs source/documentation checks, lint/design/types/unit checks, one library build, built declaration/skill and source-map checks, the installed package harness, then one preview build, in order. `check:all` adds the curated browser regression suite against that fresh static output, with zero retries. `test:browser` rebuilds the preview and runs those regressions independently. Exactly `deep-visual-audit.spec.ts` and `deep-audit-slices.spec.ts` are evidence collectors: `collect:browser` runs them separately, and their successful collection does not establish visual acceptance. Regression screenshots use per-test Playwright output paths. Set `THEMELIA_EVIDENCE_OUTPUT` to an explicit durable directory only when preserving a review; collectors also accept `AUDIT_OUTPUT`.
 
+For quality reviews, reproduce each finding, repair its shared owner, inspect the
+rendered result and execute the relevant behavior. Record those results in a
+finding ledger using the [drift review guide](docs/maintainer-skills/themelia-cn-quality/drift-audit.md).
+
 Documentation refreshes are explicit: `docs:sync-preview` owns catalogue public symbols and authored literal selection guidance, `docs:sync-props` owns local prop names/types/required flags and branch constraints, and `docs:sync-skill` owns consumer references. Checks never refresh them. Existing props prose and defaults remain reviewed metadata; native fields and undisplayed historical nonpublic records remain imported evidence. Catalog digest fields retain their historical imported scope and are not freshness checks.
 
 Browser verification requires Playwright Chromium. An existing executable can be supplied through `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH`.
@@ -60,7 +64,7 @@ export function Example() {
         <Card title="Account">
           <Stack gap="lg">
             <Input aria-label="Name" />
-            <Button onClick={() => {}}>Save</Button>
+            <Button tone="primary" onClick={() => {}}>Save</Button>
           </Stack>
         </Card>
       </ThemeScope>
@@ -71,6 +75,8 @@ export function Example() {
 
 `UIProvider` is isolated and mount-once; configuration resolves explicit prop → provider default → fallback. Use direct props for per-instance state. It supports formatting, money, dates, comments, typography, density, items, buttons, badges, cards, toasts and spinners. `ThemeScope` is a CSS inheritance host; portaled menus, tooltips and overlays stay inside the nearest scope. Explicit Base UI portal containers take precedence.
 
+The default primary is near-black, so status colors never compete with it. For the Themelia green brand, also import `themelia-react-ui/themes/green.css` after `style.css`. For your own brand, set `--primary` and `--primary-foreground` (light and `.dark`) at the root or a `ThemeScope`; `--primary-accent` follows `--primary`.
+
 Compiled `style.css` requires no source scanning and includes no global preflight. Your app supplies its reset. Load library CSS before app overrides. A Tailwind v4 application can additionally import `theme.css` after Tailwind to use the same mappings in its own classes; this editable file contains Tailwind directives and needs processing.
 
 React component chunks preserve `"use client"` boundaries for frameworks such as Next App Router. Pure utilities remain server-usable. Navigation uses native links, callbacks and render composition supplied by the consuming app.
@@ -136,15 +142,15 @@ The common geometry controls are:
 :root {
   --space-scale: 1;
   --density-scale: 1;
-  --gap-normal: 0.5rem;
-  --gap-dense: 0.25rem;
+  --gap-normal: 0.25rem;
+  --gap-dense: 0.125rem;
   --height-action: 2.25rem;
   --height-control: 2.25rem;
   --control-x: 0.75rem;
   --row-x: 0.75rem;
   --row-y: 0.5rem;
-  --surface-x: 1rem;
-  --surface-y: 1rem;
+  --surface-x: 1.25rem;
+  --surface-y: 1.25rem;
 }
 ```
 
@@ -153,7 +159,7 @@ The remaining roots cover icons/avatars, shell dimensions, content widths and ad
 Each default has one owner. There is no legacy token pipeline, JavaScript style engine, underscore prefix, or button-specific palette. Shared action/control, row, surface and text recipes prevent components from acquiring unrelated spacing or color systems.
 
 The additive copy-gap contract replaces scattered title/description gaps with
-`--gap-normal` (8px) and `--gap-dense` (4px), scaled once by `--space-scale`.
+`--gap-normal` (4px) and `--gap-dense` (2px), scaled once by `--space-scale`.
 Headed surfaces accept `textGap`, and Stack/Grid accept the same semantic gap
 values. Existing spacing tiers and public roots remain available.
 
@@ -175,7 +181,7 @@ previous independent row tint. Existing explicit `indent` values are supported.
 - Children override `Text.content`, including zero. Inverse text uses the inverse foreground pair across themes; primary text uses the readable brand accent.
 - Primary button labels use the shared `text-sm` role across control sizes. Secondary buttons use the shadcn secondary surface/foreground pair.
 - Filter presets and saved views retain the `FilterTabs`/`SavedViewTabs` APIs but expose pressed buttons rather than tabs without panels. Arrow/Home/End navigation selects presets; use `aria-pressed` instead of `aria-selected` when querying this control.
-- Framed surfaces use their shared semantic border and outer-ring recipe; the `framed` variant and provider defaults remain available. Card header actions stay on the trailing side in wide containers and move below the full-width identity in narrow containers. Translated titles and suffix badges wrap within the leading region.
+- Framed surfaces use their shared semantic border and outer-ring recipe; the `framed` variant and provider defaults remain available. Card headers wrap naturally when their title/copy and actions need more space, including inside differently named containers. Translated titles and suffix badges wrap within the leading region.
 - PopoverMenu matches plain labels/descriptions by default, preserves explicit `searchValue` overrides, and accepts `contentLabel`/`contentLabelledBy` for its popup name. Custom rows receive actual highlight state and own their structured markup.
 - AI copy feedback waits for a successful write. `onCopyError` and optional `strings.copyError` expose denied/unavailable writes; `onCopy` fires after success.
 - Card, badge, overlay and form geometry follows canonical shared recipes instead of obsolete source CSS module defaults. Typography has no incidental margins; structures own layout spacing.
@@ -199,15 +205,46 @@ Use `titleSuffix` for card status, count and version badges. `headerStart` is fu
 
 Application drawers use `ActionDrawer` and `useOverlayVisibility` from `themelia-react-ui/features/overlays`. Sheet is the structural foundation and remains available for lower-layer infrastructure and compatibility.
 
+Page header commands are role-based: one `primaryAction` and ordered
+`secondaryActions`, with overflow, destructive commands and narrow widths moved
+into a More actions menu. Keep `actions` for non-command controls.
+Page owns inline and block padding, defaulting to the large surface role;
+PageViewport owns scrolling and supplies no inset. Use `Page narrow` for a
+centered single resource; explicit `maxWidth` wins. Page headers use dense copy
+gaps. Ordinary cards retain default `md` padding; configure header/footer rules
+through UIProvider's `card.defaultHeaderDivider` and `card.defaultFooterDivider`.
+AppSidebar offers pinned `slots.headerStart`/`headerEnd` around its workspace
+region, compact navigation and a separated footer. The
+[complete shell recipe](docs/consumer-skill/examples/app-layout.tsx) demonstrates
+public workspace/account controls and application-owned callbacks.
+
+Choose one ordinary card surface through `card.defaultSurface`; explicit per-card
+surfaces win. Use Card's `icon` slot for routine header icons and `headerPlacement`
+to choose inside/frame composition independently. Independent framed peers
+usually use `gap="xl"`, since outer rings consume a smaller DOM gap.
+MetadataList retains medium labels and normal primary values in both densities.
+Dashboard KPIs use Metric/MetricGrid/MetricBar; quotas use the focused UsageCard
+owner. See [analytics selection](docs/consumer-skill/references/analytics.md) and
+the [resource page recipe](docs/consumer-skill/examples/detail.tsx).
+
+The dated [whole-library review](docs/verification/2026-10-14-whole-library-review.md)
+records repaired owners, rendered/interaction evidence and remaining coverage
+limits separately from package checks.
+
 Consumer integration guidance is available in [the package consumer skill](docs/consumer-skill/SKILL.md). The token contract budgets 23 structural roots and 77 package-owned roots; derived utilities are implementation recipes, not additional customization settings.
 
+Content-led websites can compose Container, Section, Stack/Grid, shared typography
+and ordinary Card subjects without app chrome. The packaged
+[website recipe](docs/consumer-skill/examples/website.tsx) demonstrates service
+offers and real navigation links using the same theme and inset owners.
+
 
-Popover content uses `type="display"` for substantive content and `type="menu"` for collections. Mixed searchable menus use flush shells and compact region insets. `rounded-radius` is the package-wide default for cards, controls and popup shells. `rounded-inner` is opt-in for nested bodies or collection items, using the existing smaller tier. No separate surface radius or new public theme variable is introduced.
+Popover content uses `type="display"` for substantive content and `type="menu"` for collections. Mixed searchable menus use flush shells and compact region insets. `--radius` defaults to 12px. Cards and popup/command shells use `rounded-radius`; controls, collection/navigation rows and nested bodies use the shared, height-bounded `rounded-inner` role (normally 9px). Both derive from the same public root. Consumers inherit these recipes; see the [theme contract](docs/consumer-skill/references/theming.md) for scaling and custom roots. No separate surface/control radius setting is introduced.
 
 
 ## Agent skill and consumer references
 
-The npm tarball ships the complete [consumer skill](docs/consumer-skill/SKILL.md), [discovery](docs/consumer-skill/references/discovery.md), [composition](docs/consumer-skill/references/composition.md), [integration](docs/consumer-skill/references/integration.md), [theme extension](docs/consumer-skill/references/theming.md) and [workflow](docs/consumer-skill/references/workflows.md) references. Its generated [public index](docs/consumer-skill/references/public-api.json) records exact imports, symbols, declarations and peer requirements; [the recipe manifest](docs/consumer-skill/examples/manifest.json) identifies all twelve runnable examples and their basic/optional phases. It contains no preview source or maintainer audit screenshots.
+The npm tarball ships the complete [consumer skill](docs/consumer-skill/SKILL.md), [discovery](docs/consumer-skill/references/discovery.md), [composition](docs/consumer-skill/references/composition.md), [integration](docs/consumer-skill/references/integration.md), [theme extension](docs/consumer-skill/references/theming.md) and [workflow](docs/consumer-skill/references/workflows.md) references. Its generated [public index](docs/consumer-skill/references/public-api.json) records exact imports, symbols, declarations and peer requirements; [the recipe manifest](docs/consumer-skill/examples/manifest.json) identifies all runnable recipes and their basic/optional phases. It contains no preview source or maintainer audit screenshots.
 
 After installing the package, find a family using its real portable script:
 
@@ -219,8 +256,8 @@ Resolve the installed package and compare copied guidance using the [installed s
 
 Repository work uses the scoped [maintainer](docs/maintainer-skills/themelia-cn-maintainer/SKILL.md), [tokens](docs/maintainer-skills/themelia-cn-tokens/SKILL.md) and [quality](docs/maintainer-skills/themelia-cn-quality/SKILL.md) skills routed by [AGENTS.md](AGENTS.md). These repo-owned guides are excluded from the consumer package and do not replace separately installed skills.
 
-There is one packaged consumer skill with eight focused prose references, two
-generated indexes, twelve typed recipes and five helper scripts. Repository
+There is one packaged consumer skill with nine focused prose references, two
+generated indexes, fourteen typed recipe files and five helper scripts. Repository
 maintainer skills remain separate. The consumer entrypoint starts from task,
 context, information priority and command ownership and routes typography,
 layouts, theming, state/integration and verification detail to the relevant owner.
@@ -233,11 +270,15 @@ is a warning and dynamic/external styling needs review. `check:agent` verifies
 deterministic guidance infrastructure, not aesthetic judgment or new-task agent
 performance. Keep app-specific policy separate from the versioned package skill.
 
-Maintainers run `npm run docs:sync-skill` after changes to exports, types, selection guidance, peers or tokens. `npm run check:skill` requires a fresh library build and rejects stale source-backed references, built declaration exports and broken reference links. `prepack` checks source-backed references without rebuilding; `prepublishOnly` builds fresh assets and verifies built guidance. `check:package` verifies the complete shipped skill, then strictly compiles the eight basic recipes without optional peers and all twelve with their needed peers, alongside its installed runtime checks.
+Finder results include relevant symbols and focused next reads for declarations,
+references and exported recipes. This reduces the need to infer a component's
+purpose from its name or read every document before starting a screen.
 
-Build portable consumer documentation with `npm run build` followed by `npm run build:docs`. The generated [static entry](dist-docs/index.html) links to `dist-docs/1.0.1/` for the current version. Each version preserves the complete skill and all declaration files, supports search with the same finder, and uses relative links under any hosting subdirectory. Serve the entire artifact over HTTP; it needs no external CDN. Run `npm run check:static-docs` to check generated asset paths. The future hosting destination remains pending.
+Maintainers run `npm run docs:sync-skill` after changes to exports, types, selection guidance, peers or tokens. `npm run check:skill` requires a fresh library build and rejects stale source-backed references, built declaration exports and broken reference links. `prepack` checks source-backed references without rebuilding; `prepublishOnly` builds fresh assets and verifies built guidance. `check:package` verifies the complete shipped skill, strictly compiles the basic recipes without optional peers and every recipe with its required peers, and executes installed shell/resource-page and workflow checks.
 
-`npm run check:agent` runs focused agent-consumption fixtures and built skill alignment. `npm run check:release` performs the real serial local build/package/browser/agent/static-documentation gate; it does not publish or deploy. See the [release guide](docs/releasing.md), [draft changelog](CHANGELOG.md) and [future GitHub Actions template](.github/workflows/ci.yml) for browser installation and explicit cold-cache handling. These commands verify locally; publication and deployment remain separate actions.
+Build portable consumer documentation with `npm run build` followed by `npm run build:docs`. The generated [static entry](dist-docs/index.html) links to `dist-docs/2.0.0/` for the current version. Each version preserves the complete skill and all declaration files, supports search with the same finder, and uses relative links under any hosting subdirectory. Serve the entire artifact over HTTP; it needs no external CDN. Run `npm run check:static-docs` to check generated asset paths. The future hosting destination remains pending.
+
+`npm run check:agent` runs focused agent-consumption fixtures and built skill alignment. `npm run check:release` performs the real serial local build/package/browser/agent/static-documentation gate; it does not publish or deploy. `npm run check:quick` runs the everyday core (contract, lint, design lint, typecheck, unit tests, build). See the [release guide](docs/releasing.md) and [draft changelog](CHANGELOG.md). There is no hosted CI; every check runs locally, when you choose. These commands verify locally; publication and deployment remain separate actions.
 
 This package uses the [MIT license](LICENSE). Adapted shadcn/ui scaffolding retains its MIT attribution in [third-party notices](THIRD_PARTY_NOTICES.md). Package repository and issue metadata follow the configured Git remote. Repository-only links above describe checkout tooling; the complete consumer skill is shipped in the npm payload.
 
@@ -281,3 +322,13 @@ These families add no runtime dependencies or public token roots. AppSidebar's
 `searchable` option and controlled branch expansion extend the existing sidebar;
 routing and persistence remain consumer-owned. See the catalogue and packaged
 consumer recipes for the exact contracts.
+
+Heading keeps semantic `tag` separate from optional visual `size` (`sm`, `base`,
+`lg`, `xl`, `2xl`, `3xl`, `4xl`), using existing typography variables. The admin
+default remains `base`; website examples opt into larger emphasis. Metric card,
+bordered, accent and colored values use that shared scale. A card metric's `href`
+is a native link; `onClick` without `href` is a native action.
+
+Base Table exposes `containerProps` for the single scroll/focus wrapper;
+`className` and other native table attributes still apply to the table itself.
+DataTable uses that same wrapper for its localized scroll-region name.