themelia-react-ui 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,356 @@
 # Changelog
 
+## 2.0.1 — 2026-10-18
+
+One shared recipe and design-lint rule for each visual state, the fixes the new
+drift checks found, and one command row and record-page recipe for every page
+header. No public export or prop is removed. Additions: `header.tabs` on Page
+(`PageHeaderTabs`); `primaryAction`, `secondaryActions`, `moreActionsLabel` and
+`renderLink` on PageHeading, ResourceHeader, the resource shells and
+SettingsShell, and `primaryAction` on WorkspaceRecordHeader;
+`toPageHeaderAction` in `services/actions`; an optional `toggle` flag on
+`ToolbarButtonConfig` and `RichTextEditorToolbarItem`; `context` on
+`ActionMenu` (`ActionMenuContext`); an optional `actions.menuLabel` in DataTable
+strings; `align` on ConfirmDialog and ActionDialog with UIProvider overlay
+defaults; `selecting`, `defaultSelecting`, `onSelectingChange` and `onItemOpen`
+on MediaLibrary; `useRichTextImages` and `images` on RichTextEditor and
+RichText; the `themelia-react-ui/base/metadata-list` entrypoint; an optional
+`fontFamily` on `signaturePadToSVG`; the `themelia-react-ui/base/batch-action-bar`
+entrypoint; the order blocks, `SummaryPanel` and `AmountRow` in `blocks/commerce`;
+`valueAlign` on MetadataList; `defaultValue`, `name` and ARIA props on TagsInput.
+`PageActions`, `PageAction`,
+`toPageAction`, `features/sync`, the standalone product region cards, the
+`blocks/data-display` MetadataList exports and `ActivityRow` `moreLabel` are
+deprecated.
+
+### Upgrading from 2.0.0
+
+- **Focus and control borders.** Library controls draw the soft `--input`
+  boundary and one shared focus indicator. Drop `ring-2`, `ring-offset-*` or
+  full-strength `ring-ring` focus classes passed to library controls; the
+  consumer checker reports them as `focus-ring-recipe`. Themes that override
+  `--ring` should keep it at 3:1 against their surfaces.
+- **Page commands.** Replace a `PageActions` ribbon or hand-built buttons in a
+  header's `actions` with `primaryAction` (one) and ordered `secondaryActions`;
+  mark irreversible commands `destructive: true` and confirm them in the
+  handler. `actions` stays for non-command controls such as a period select.
+  Move section tabs placed at the top of a Page body into `header.tabs`. The
+  consumer checker reports the old shapes as `page-command-roles`.
+- **Overflow trigger names.** Overflow triggers are named "More actions" by
+  default. This replaces "Open menu" (`ActionMenu` `strings.openMenuLabel`),
+  "Card actions" (Card `actionsLabel`), "Actions" (ContentBlock and DataTable
+  row menus) and "Page actions" (`PageActions` `strings.menuLabel`). Update
+  tests or automation that find these buttons by name, or pass the old copy
+  through those strings. The DataTable actions column header stays "Actions"
+  (`strings.actions.triggerLabel`); the row trigger's name moves to the new
+  `strings.actions.menuLabel`. Copy that sets only `triggerLabel`, as localized
+  tables did before, keeps naming the trigger with it.
+- **Overflow trigger size and glyph.** An icon-only `ActionMenu` trigger now
+  follows `UIProvider.density.defaultScale` instead of always rendering at
+  `md`; pass `buttonProps.size` to match the controls beside it. The default
+  glyph is the horizontal ellipsis (`MoreHorizontal`) rather than
+  `MoreVertical`; `icon` still overrides it.
+- **State styling.** Hover, selection, pressed, status-tint, divider, disabled,
+  motion, corner and stacking classes passed to library rows and tiles should
+  follow the shared roles below. Pressed toggles, including AI feedback votes,
+  editor formatting buttons and the editor's source view, show the accent fill
+  instead of a status colour or a solid primary fill. `HighlightedText`'s
+  default `highlightClassName` is the shared match mark: foreground text on the
+  warning tint.
+- **MetadataList moved to base.** Import `MetadataList`, its item types and
+  default strings from `themelia-react-ui/base/metadata-list`. The
+  `themelia-react-ui/blocks/data-display` re-exports keep working and are
+  deprecated. Labels render semibold.
+- **MediaLibrary opens before it selects.** Activating an asset (click, Enter,
+  Space) calls `onItemOpen` or shows the details panel. Selection is an explicit
+  mode: `selecting`, `defaultSelecting` and `onSelectingChange`. Picker dialogs
+  start selecting; pass `defaultSelecting` where a library relied on selecting
+  by default.
+- **ConfirmDialog is centred.** ConfirmDialog and ActionDialog accept
+  `align: 'start' | 'center'`, resolved from the prop, then the UIProvider
+  `overlay.defaultConfirmAlign` / `overlay.defaultDialogAlign` defaults, then
+  center for ConfirmDialog and start for ActionDialog.
+- **Deprecated: `themelia-react-ui/features/sync`.** `SyncRangeDialogForm` is
+  application-specific; use `SchemaForm` with `radio-cards` and
+  `checkbox-cards` fields. The entrypoint still ships.
+- **Deprecated: standalone product region cards and row menus.** Render them
+  through `ProductOverview` slots and the `renderOptionActions` /
+  `renderVariantActions` options. They stay exported.
+- **Deprecated: `ActivityRow` `moreLabel`.** The collapsed metadata preview it
+  labelled is gone; secondary detail opens with the details disclosure.
+- **Selection bars are a `BatchActionBar`.** DataTable's default selection
+  toolbar now docks to the bottom of the viewport (`floating`); pass
+  `selectionToolbarPlacement="inline"` to keep it in the table. Its summary and
+  the new `totalRowCount` prop default to `pagination.total`, so server-paginated
+  tables count the whole result. Product variant tables show an inline bar only
+  while variants are selected; `renderBulkActions` now replaces the default
+  commands, as documented (return `null` to keep them), and Delete no longer
+  repeats the count.
+- **MetadataList rows.** `layout="rows"` draws rules only with `itemSeparator`,
+  and values start their column on `2fr/3fr` tracks. Pass `valueAlign="end"` for
+  the previous right-aligned figures, such as money columns.
+- **TagsInput.** Chips sit inside the field, before the text input in Tab order;
+  the count and clear-all move to a footer under the field, and the placeholder
+  shows only while the field is empty. The input stays enabled at `maxTags`.
+- **Commerce DOM hooks.** RefundStatusCard, CartSummaryCard,
+  DiscountStackPreview, TaxBreakdownCard and ShipmentTracking render on `Card`
+  and lose the `content-block--*` classes and `data-component="content-block"`;
+  their own `--component` classes stay. ShipmentTracking and InvoiceHeader show
+  a visible title with the status chip in its suffix.
+
+### Changes
+
+- **Visual: the More actions menu ends the page header's command row.** Page
+  commands render as the secondary commands, then the primary command, then the
+  More actions menu (`[secondary…] [primary] [⋯]`); 2.0.0 placed the menu
+  between the secondary and primary commands. The menu trigger takes the
+  secondary treatment, an outline square at the commands' own height, including
+  under a compact `UIProvider` scale; it was a ghost glyph at the default size.
+- **Visual: one overflow trigger.** Every overflow menu shares one `ActionMenu`
+  trigger recipe (`action-menu.recipes.ts`). It draws the `⋯` glyph, is named
+  "More actions", and is a square at the size of the controls beside it, or at
+  the provider scale when nothing sits beside it. `context="inline"`, the
+  default, is a quiet ghost square with a muted glyph for rows, cards and
+  footers. `context="commands"` is the outline square beside outline commands,
+  which the page header's More actions trigger now takes from the recipe.
+  Card headers, DataTable rows, Kanban items and the EmailComposer footer
+  follow the provider scale. Activity rows and ApiKeyList match their own
+  compact expand and add controls. `PageActions` uses the outline treatment at
+  its inline `size`. The library no longer hand-sets trigger sizes, styles or
+  glyphs.
+- **The menu ends any row with a primary command.** The EmailComposer footer
+  renders `[Discard] … [Send] [⋯]`, where 2.0.0 placed the menu before Send.
+  Send and the menu wrap together, so the menu never sits alone on a narrow
+  line.
+- **One menu per header, destructive commands last.** `ProductVariantDetails`
+  merges its default variant commands (Open, Edit, Duplicate, Delete) into the
+  card's own `actions` menu. Its header no longer shows a second, differently
+  sized `⋯`, and Delete sorts last. A custom `renderActions` still renders in
+  the header. The product variants bulk bar places Delete after Apply and any
+  `renderBulkActions` content.
+- **Overflow trigger enforcement.** The `overflow-trigger` rule in
+  `check:contract` rejects overflow glyph imports outside the ActionMenu owner,
+  raw UI, pagination and the OverflowTabBar More tab. It also rejects icon-only
+  `ActionMenu` triggers that set `tone`, `buttonStyle`, `iconOnly` or
+  action-size classes through `buttonProps`.
+  `tests/browser/overflow-trigger.spec.ts` checks order, heights and every
+  opened menu at 390px and 1440px in light and dark.
+- **One command row for every header.** PageHeading owns the role-based row,
+  and `PageHeaderAction` moves to `base/navigation` (still exported from
+  `layout/page`). Page and PageHeader pass their commands to it; ResourceHeader,
+  ResourceIndexShell, ResourceShowShell and TabbedResourceShell
+  (`ResourceHeaderCommandProps`), SettingsShell and WorkspaceRecordHeader take
+  the same `primaryAction` and `secondaryActions` and render the same row after
+  their custom `actions`. WorkspaceRecordHeader's `secondaryActions` accepts
+  command objects; rendered elements keep their previous cluster.
+- **Section tabs in the page header.** `header.tabs` renders a record's
+  sections under the header's copy and commands with the shared OverflowTabBar:
+  `badge` shows a count, tabs that do not fit move into a More menu, the active
+  tab stays visible, and `onValueChange` switches the section or routes.
+- **Deprecated `PageActions`.** Its ribbon defaulted inline commands to solid
+  secondary buttons beside a larger ghost menu trigger and collapsed by viewport
+  width. Pass commands by role instead, or use ActionButtons for a toolbar.
+  `toPageHeaderAction` adapts a resolved action to a role-based command, with a
+  destructive tone marking it destructive.
+- **One record-page recipe.** The detail recipe, the resource-detail build
+  recipe and a new Page example show a record with one status badge,
+  role-based commands, a confirmed destructive command and section tabs with
+  counts. Catalogue examples for PageHeading, resources, workspaces, settings,
+  app shells and tables use role-based commands; the consumer docs no longer
+  recommend card dividers, footer command rows or decorative title icons.
+- **Consumer checker.** `page-command-roles` also flags PageActions,
+  ActionButtons and ActionMenu in a header's `actions`, and covers PageHeading,
+  the resource shells, WorkspaceRecordHeader and SettingsShell.
+  `decorative-icon` flags a page `titleIcon` without a link or handler, and an
+  icon on more than one page command. `raw-button` no longer flags a native
+  button passed as a package owner's `render`, such as an Item row rendered as
+  a button; the owner keeps that root's focus edge and row anatomy. Local
+  components passing a native button are still reviewed.
+- **Teaching material follows the house rules.** Catalogue examples, templates
+  and the shipped consumer examples use an untoned Button for neutral commands
+  (a `tone="secondary"` Button without `buttonStyle` renders solid), spell
+  neutral badges `tone="neutral"`, space siblings with Stack, Grid and
+  AdaptiveGrid instead of flex/grid gap divs or `space-y` margins, and drop
+  decorative title tiles. The order, product, customer, staff and overview
+  templates keep Page's default measure; the order template's fulfillment is
+  its `header.primaryAction`, the staff template's suspension is a
+  `destructive: true` secondary action confirmed by ConfirmDialog, and neither
+  repeats the header's status badge in a card or fact list.
+- **Agent guidance closes the loop.** The consumer skill ships a project
+  instructions block (`references/agents-md.md`) to paste into an app's
+  `AGENTS.md`: under 2,000 characters, version-stamped in its start marker,
+  generated and verified by `check:skill`, and naming only scripts that ship
+  with the skill. The installed identity recipe reports the block as missing,
+  current or stale. SKILL.md and the review guide now make the composition
+  checker the agent's done condition (no errors on changed files, at most three
+  fix rounds, then the app's typecheck, lint and tests) with a five-line
+  hand-back, instead of calling it optional.
+- **Consumer-skill evals.** `evals/consumer-skill` holds eight admin tasks,
+  five of them temptations such as a red Delete button or hand-made KPI cards,
+  each with a reference and a naive solution. `scripts/consumer-evals.mjs`
+  scores agent outputs with the shipped checker, imports and source patterns,
+  and `check:agent` proves every reference passes and every naive version fails.
+- **Fix: destructive activity actions.** ActivityFeed row menus passed the
+  action tone as an unknown `variant` field, so a destructive action lost its
+  destructive treatment and its place at the end of the menu.
+- **Visual: one control boundary and one focus indicator.** `--input` is the
+  single control boundary: fields, select and date triggers, checkboxes, radios,
+  switch tracks, upload targets and outline buttons all draw it, so adjoining
+  controls read as one family. It is now soft and translucent
+  (`oklch(0.28 0 0 / 15%)` in light, white at 15% in dark) and reads the same on
+  every surface, replacing the 3:1 gray of 2.0.0 (`oklch(0.62 0 0)`, white at
+  40% in dark) that made fields and selects read darker than the outline buttons
+  beside them; `--border` stays the divider color, and the repeater's empty
+  placeholder uses it. Every focused element draws one indicator from
+  `src/lib/focus-recipes.ts`: a 1px `--ring` edge at full strength (the
+  control's own border, an inset edge on borderless rows and regions, or an
+  outline just outside link and text-button glyphs) inside a soft 3px halo of
+  `--ring` at 50%. It replaces the 2px full-strength and offset rings, which
+  read as a heavier border. The edge carries the 3:1 contrast. An invalid field
+  keeps its destructive border at rest and while focused, where the halo turns
+  destructive; there is no resting halo. Focus on a MediaGallery tile is drawn
+  inside the tile, where its overflow clipping had hidden it. Design lint's
+  `focus-ring-recipe` rule (replacing `focus-ring-contrast`) rejects other focus
+  ring widths, offsets and halo strengths in library source and on imported
+  consumer controls. The contrast contract keeps `--ring` and `--sidebar-ring`
+  at 3:1 and checks `--input` against a 1.3:1 visibility floor on background,
+  card, popover, muted, accent and secondary surfaces.
+- **Visual: one recipe per state family.** Each family that had several local
+  spellings now has one owner and a design-lint rule that cannot acquire
+  migration debt.
+  - Rows (navigation, lists, trees, results, menus) hover and select with
+    `--accent`, and the current location adds medium weight, so a hover never
+    reads as current. Ghost and outline buttons hover with the same fill and its
+    `--accent-foreground`; a component's own hover colour still wins.
+  - Toggles hover with `--muted` and press with `--accent`. Tables keep a
+    quieter `muted` ladder for stripes, hover and selection. Segmented tracks
+    lift the active segment to `--card`.
+  - Text never takes opacity: faded secondary text, which fell under 4.5:1, uses
+    the typography roles.
+  - Dividers are `--border` at full strength on surface edges and at 60% between
+    rows.
+  - Disabled content dims once, to 50%.
+  - Status and emphasis tints use one scale per tone
+    (`src/lib/tone-recipes.ts`): a wash for large surfaces, a tint for chips,
+    badges and icon tiles, and an edge, halo and line strength. The contrast
+    contract tests each tone's ink on its tint. Badges, alerts, avatars, icon
+    tiles, activity, search, calendar, timeline, commerce and AI blocks share
+    it. Search matches and edit diffs use one inline mark, and the heatmap and
+    distribution ruler keep their data ramps.
+  - Colour, border and shadow state changes keep the default 150ms transition.
+  - Corners derive from `--radius`: the fixed 4px `rounded` and the t-shirt
+    steps in raw UI, skeletons and chips are gone.
+  - Stacking uses one scale: raised, sticky, sticky over sticky, chrome and
+    overlay.
+  - SectionNav links gain the shared focus indicator, borderless Item rows draw
+    the focus edge inset, and the column-resize handle marks focus in the ring
+    colour.
+  - Neutral fills use one strength per role: a wash for quiet regions, a band
+    for header, toolbar and footer strips, a solid track, a neutral chip and
+    neutral markers. Twenty strengths become five. Table heads, toolbars, empty
+    states, AI panels, auth and workspace regions, tab tracks, meters and
+    carousel dots share them.
+  - Elevation uses one theme shadow per role: resting, card, raised, lifted and
+    modal. The command palette's 2xl shadow, two custom table-frame shadows
+    (which glowed in dark mode) and a shadow colour override are gone.
+  - Keyboard-shortcut hints in the header search trigger and the global search
+    footer share one key-cap style.
+  - Floating chips over media, lifted panels over the auth art and the chat
+    composer band are opaque.
+  - A drift census budgets each family's vocabulary in `check:design-lint`, and
+    a rendered role-parity browser check measures hover, current, disabled and
+    focus in light and dark.
+- Rich-text toolbar toggles announce their state. Built-in format buttons and
+  the source view expose `aria-pressed`; undo and redo do not.
+  `ToolbarButtonConfig` and `RichTextEditorToolbarItem` gain an optional
+  `toggle` flag; an extra toolbar item with `isActive` is a toggle unless it
+  sets `toggle: false`.
+- Item titles that cannot fit end in an ellipsis on their text. The title row is
+  a flex container, where `text-overflow` has no effect, so a long token was
+  clipped mid-glyph instead: an applied coupon `SPRING2026` read as `SPRING202`.
+  Truncating titles in citations, vendor profiles, gift cards and attachments
+  benefit too. The applied coupon also carries its full code as a `title`.
+- **Overlays draw one rule per region boundary.** ActionDialog, ActionDrawer
+  and ConfirmDialog separate header, body and footer with a rule, and a dialog
+  without a body shows a single rule.
+- **Rich text images.** RichTextEditor and RichText support images through
+  `useRichTextImages`: the consumer owns `upload(file, { signal })`; the library
+  owns toolbar, paste and drop insertion, the upload placeholder, cancel, retry
+  and remove, type and size limits, alt text and the http/https/blob/relative
+  source policy. `renderImage` draws read-only images with the consumer's
+  component.
+- **RichTextEditor runs Tiptap.** Its runtime check required `EditorContent`
+  to be a function, but Tiptap 3 exports it as `React.memo`, so every editor
+  (rich text, comment, activity and email composers) silently rendered the
+  contenteditable fallback with formatting disabled. Picking a mention in Tiptap
+  now replaces its `@query` instead of appending after it, and the editor chip
+  keeps the `.rsc-mention` hook, so mention-chip.css draws it in both engines.
+- **Mentions insert as atomic badge chips** removed by one Backspace. The
+  suggestion list and picker are more compact, and kind filters use the shared
+  toggle style.
+- **Global search** builds its field on the public `InputGroup` and lays out
+  results, group headings and the footer with the compact Command recipe.
+- **Activities open compact.** Rich rows show the headline and description;
+  metadata, changes, details, resource chips and inline actions appear together
+  behind "Show details".
+- **Comments** no longer leave an empty band under each comment's action row.
+- **Choice inputs centre on the label line.** Checkbox, radio, switch and
+  selected-card checks share one label-line track (questionnaire,
+  ApiTokenManager, card groups).
+- **One plain X clears fields.** Input, Textarea, Cascader, Combobox and global
+  search clear actions, and TagsInput and Combobox chip removes, draw a plain X
+  instead of a circled X.
+- **Cascader** draws Input's field frame and the shared Combobox affordance
+  track; its clear sits beside a chevron aligned with Select's.
+- **Visual: Badge `sm` and `md` are 2px taller** (20px and 23px) at the same
+  type size; inline badges are unchanged, and TagsInput chips follow.
+- **NavigationTabs** keeps the current tab lifted under hover and press;
+  inactive tabs change colour only.
+- **SignaturePad** draws, exports and previews typed names in the pad's font
+  (theme sans by default) instead of `cursive`, and fits long names by font
+  size; `signaturePadToSVG` accepts an optional `fontFamily`.
+- **Fixes:** Dropzone centres both copy lines; IconBadge sizes child glyphs with
+  its icon role (SmartAccordion medallions render at 16px); Alert's icon and
+  action columns use Toast's 8px gap; content typography fits images to the
+  column.
+- **Catalogue:** the deprecated Sheet page, the products main-column, actions
+  and support-rail pages and the sync page are retired; their URLs redirect to
+  the overlays, product overview and SchemaForm pages.
+- **BatchActionBar** (`themelia-react-ui/base/batch-action-bar`): one selection
+  bar with a count, bulk actions and Clear, `floating` (docked, lifted, opaque)
+  or `inline`. The count is a polite live region, Escape inside the bar clears,
+  and focus returns to the list (or `returnFocusRef`) when the bar goes away.
+  DataTable, product variants and MediaLibrary's new `bulkActions` use it; the
+  old sticky selection toolbar and its overlap with the sticky topbar are gone.
+- **Order blocks** in `blocks/commerce`: `OrderHeader` (payment and fulfilment
+  status axes), `FulfillmentGroup`, `OrderLineItem`, `OrderSummary`,
+  `OrderTransactions` and `OrderCustomer`, with an Orders catalogue group and an
+  Order detail composition. The shared money ledger `SummaryPanel` and
+  `AmountRow` now draw CartSummaryCard, TaxBreakdownCard, DiscountStackPreview,
+  InvoiceHeader and OrderSummary: no tinted box, one rule above a grand total.
+- **Commerce blocks follow the source kit.** ShipmentTracking has a copyable
+  tracking number (`onCopyTracking`) and a timestamped checkpoint rail whose
+  current step is `aria-current="step"`; RefundStatusCard is an ordered list of
+  stages; PaymentMethod gains `variant="row"` and speaks `strings.formatCard`
+  ("Visa ending 4242"); CartSummaryCard falls back to initials on a failed image
+  and adds `strings.formatQuantity`; DiscountStackPreview takes an optional
+  `kind` and `id`. Blocks pass native attributes to their root. `CartSummary`,
+  `DiscountStack`, `RefundStatus` and `PaymentMethodCard` are added as the source
+  kit's names for the same components. `Timeline` items expose `data-status` and
+  mark the current item `aria-current="step"`.
+- **MetadataList** labels wrap in every layout and stay semibold; inline
+  `itemSeparator` is a middle dot hidden from screen readers; `render` output
+  takes the value style; the info trigger no longer grows its line; `icon` takes
+  any `ComponentType<{ className?: string }>`.
+- **TagsInput fixes.** Multi-tag paste commits every tag, `sortTags` removes the
+  right tag, object tags are created from an empty value, a refused entry no
+  longer traps Tab, IME composition no longer commits, a typed delimiter splits,
+  single-token paste is native, and focus moves to the neighbouring chip after a
+  removal. Refused entries stay in the draft and are announced
+  (`strings.notAdded`). New `defaultValue`, `name` (hidden `name[]` inputs) and
+  ARIA pass-through; `TagsInputStrings` and `defaultTagsInputStrings` are
+  exported.
+
 ## 2.0.0 — 2026-10-16
 
 A major release. Untouched defaults now give a screen one deliberate primary

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: **`2.0.0`** · MIT licensed.
+Package: **`themelia-react-ui`** · current version: **`2.0.1`** · 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
@@ -95,7 +95,7 @@ The shipped stylesheet follows `prefers-reduced-motion` automatically for these
 | Base | `base/<family>` — controls, forms, buttons, cards, structure, navigation, menus, feedback, display, tables, uploads and specialist controls |
 | Layout | `layout`, `layout/<family>` — application shell, authentication, containers, page, settings, header, navigation, sidebar, workspace and hooks |
 | Blocks | `blocks/admin`, `ai`, `analytics`, `commerce`, `data-display`, `onboarding`, `timelines` (each prefixed `blocks/`) |
-| Features | `features/activities`, `ai-chat`, `async-preview`, `combobox`, `comments`, `data-view`, `email-composer`, `event-calendar`, `filters`, `global-search`, `kanban`, `map`, `media-library`, `mentions`, `overlays`, `products`, `resource`, `resource-assignment`, `rich-text-editor`, `schema-form`, `suggestions`, `sync`, `table`, `theme-tweaker` (each prefixed `features/`) |
+| Features | `features/activities`, `ai-chat`, `async-preview`, `combobox`, `comments`, `data-view`, `email-composer`, `event-calendar`, `filters`, `global-search`, `kanban`, `map`, `media-library`, `mentions`, `overlays`, `products`, `resource`, `resource-assignment`, `rich-text-editor`, `schema-form`, `suggestions`, `sync` (deprecated), `table`, `theme-tweaker` (each prefixed `features/`) |
 
 The complete machine-readable entry inventory is `scripts/entries.json`. Dialogs and confirmations use `ActionDialog`, `ActionDrawer`, `ConfirmDialog` and visibility/action hooks from `features/overlays`.
 
@@ -201,28 +201,41 @@ The default development URL opens the full component catalogue. The focused foun
 
 `Button` separates `tone` from `buttonStyle` (`solid`, `outline`, `ghost`); the catalogue shows their matrix, sizes and loading/disabled states. Icon-only controls may omit children when an accessible label or tooltip is supplied. Badges use compact typography and insets rather than inheriting action geometry.
 
-Use `titleSuffix` for card status, count and version badges. `headerStart` is full-width pre-title context, and `headerAction`/`actions` own controls. Card owns token-spaced title/suffix wrapping for all surface modes. Put card-level actions in `footerSlot` with `footerDivider`; reserve body actions for a specific content step. Card owns aligned card insets, frames and expand/collapse behavior; Use `Card surface="flat" padding="none"` for card-free content hierarchy. ChartCard exposes `titleSuffix` too. Use `headerPlacement="frame"` for a header above an inset body. SmartCard and ContentBlock remain deprecated migration adapters; new code uses Card.
+Use `titleSuffix` for card status, count and version badges. `headerStart` is full-width pre-title context, and `headerAction`/`actions` own controls. Card owns token-spaced title/suffix wrapping for all surface modes. Give a card one quick control in `headerAction`, a command list in `actions` (its More actions menu) and the commit action in `footerSlot`; spacing, not a divider, separates the footer. Reserve body actions for a specific content step. Card owns aligned card insets, frames and expand/collapse behavior; Use `Card surface="flat" padding="none"` for card-free content hierarchy. ChartCard exposes `titleSuffix` too. Use `headerPlacement="frame"` for a header above an inset body. SmartCard and ContentBlock remain deprecated migration adapters; new code uses Card.
 
 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.
+Header commands are role-based: one `primaryAction` and ordered
+`secondaryActions` render as `[secondary…] [primary] [⋯]`, with overflow,
+destructive commands and narrow widths moved into the More actions menu that
+ends the row. Page, PageHeader, PageHeading, the resource shells,
+WorkspaceRecordHeader and SettingsShell share that row; keep `actions` for
+non-command controls. `header.tabs` puts a record's section tabs, with counts,
+under its header.
+
+Every overflow menu shares one `ActionMenu` trigger: the `⋯` glyph named "More
+actions", a quiet ghost square in rows and cards (`context="inline"`, the
+default) or an outline square beside outline commands (`context="commands"`),
+at the size of the controls beside it (`buttonProps.size`) or the provider
+scale. The menu comes after any primary command in its row, and destructive
+entries stay last.
 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`.
+gaps. Ordinary cards retain default `md` padding and separate header, body and
+footer by spacing; `card.defaultHeaderDivider` and `card.defaultFooterDivider`
+remain for an app whose design calls for rules.
 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.
+surfaces win. Leave Card's `icon` slot for a glyph that carries state or a
+brand; titles name the subject. `headerPlacement` chooses inside/frame
+composition independently. Independent framed peers use `gap="2xl"`, matching
+Page and TwoColumnLayout's rhythm, since outer rings consume a smaller DOM gap.
+MetadataList (`themelia-react-ui/base/metadata-list`) keeps semibold 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).
@@ -276,7 +289,7 @@ purpose from its name or read every document before starting a screen.
 
 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.
 
-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.
+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.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.
 
 `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.