themelia-react-ui 2.0.5 → 2.0.6

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

@@ -81,6 +81,13 @@ application decision; confirm destructive commands in their handler. Use
 the compatible direct `actions` prop for non-command controls such as a period select. A back link,
 export and destructive command should not all inherit the same visual emphasis.
 
+Scope this hierarchy to route commands. A local lookup or independently saved
+settings form keeps its primary submit beside its fields or in its own footer;
+it does not compete with the route's primary action. A whole-page editor can
+deliberately expose one submit in its header. Preserve native form association
+and validation instead of moving local saves to header DOM-lookup handlers just
+to silence a primary-command warning.
+
 ```tsx
 <Page header={{
   title: 'Contacts',
@@ -346,8 +353,9 @@ PopoverContent type="display" owns substantive-content padding; type="menu" comp
 | size="sm" / "md" / "lg" | Supported control's scale; consult its declaration and provider precedence |
 
 Input, Button, Select, filter-facet triggers and badges share the default
-`rounded-radius` corner and corresponding heights; Card and popup shells use the
-larger `rounded-surface`. Omitted sizes inherit the provider; explicit sizes win.
+`rounded-radius` corner; Card and popup shells use the larger `rounded-surface`.
+Fields and actions use their corresponding height scales; badges remain content-sized.
+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 does not change
 the corner.
@@ -355,7 +363,7 @@ 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, rich display padding is 24px and compact collection shell padding is 8px; row inline padding is 12px; default row block padding is 8px and minimum height 32px. 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 (4px inline). Header text and footer captions add a small xs step (4px) to the md band inset (8px), rather than the full row inset. Actions keep the 4px shell edge. Nested public slots do not repeat these insets.
+At shipped roots, rich display padding is 24px and compact collection shell padding is 8px; row inline padding is 12px. Anchored collection rows use 6px block padding and a 32px minimum height by default. Compact/comfortable rows use 2/8px block padding and 28/36px minimum heights. These differ from Item/table row density recipes; content can grow when it wraps. These are token-derived measurements, not app constants. Flush compact header/footer bands match the list's 8px inset. Plain header text and footer captions add a small xs step (4px) to that md band inset, rather than the full row inset; leading controls and actions stay on the band edge. Nested public slots do not repeat these insets.
 
 Input frames and outline buttons share the input semantic token; collection dividers use border/60; focus uses ring separately and draws one indicator everywhere (a full-strength edge inside a soft halo). Equal responsibilities share recipes, while different semantic roles retain their own treatment. CommandInput keeps its existing onValueChange search contract and native refs; use the actual public Input through its default composition rather than restyling an unframed native field.
 
@@ -367,7 +375,10 @@ Overflow menus use ActionMenu's own trigger: the ⋯ glyph named "More actions",
 
 ## Migration
 
-Use exact themelia-react-ui paths. Presentation imports use blocks/<family>, replacing composed/<family>. Raw UI, Radix, cmdk and routers are not consumer foundations. Read installed types instead of assuming historical CSS-kit props.
+Use exact `themelia-react-ui` paths. Presentation imports move from
+`admin-ui-starter-kit/composed/<family>` to `themelia-react-ui/blocks/<family>`.
+Read `MIGRATION.md` in the installed package for setup, tools and changed
+defaults. Check the installed types when migrating a composition.
 
 
 ## Copy rhythm
@@ -607,6 +618,12 @@ narrow record measure, a status badge, route-level commands and section tabs in
 the header, and MetadataList facts in one framed Card, with no duplicated subject
 header or gutter.
 
+Page's measure contains both header and body. On a mixed route with wide tables
+and focused settings panels, keep Page's width stable across tabs. Constrain
+only the focused panel with `Container maxWidth="md" gutter="none"`; Container
+uses `gutter`, not a `padding` prop. An intentional responsive route width is
+different from changing the header's width on every section selection.
+
 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

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

@@ -68,6 +68,7 @@ These base measurements use the shipped roots; spacing scales once through
 | Independent subject regions | `2xl`, 24px | Page body, TwoColumnLayout, resource, workspace and settings subjects |
 | Page header/body separation | `3xl`, 32px | Page composition |
 | Surface header/body/footer | Surface-derived regional gap | Card or overlay anatomy, independent of peer gaps |
+| Live table outer / interior cell insets | Small surface / row inline tiers, 16 / 12px | Table head, body and footer cells; row density changes only block rhythm |
 
 Generic Stack and Grid keep their existing defaults; choose their semantic gap
 for the relationship they host. A Card's regional gap derives from its surface

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

@@ -2,7 +2,7 @@
 
 ## Choose the CSS path
 
-**Standalone compiled CSS:** import `themelia-react-ui/style.css` once in the app entry. It includes component styles and the documented public utility vocabulary; components work without a host reset, Tailwind processing or private-source scanning. It deliberately omits global preflight. This path does not generate arbitrary utility classes written in app source.
+**Standalone compiled CSS:** import `themelia-react-ui/style.css` once in the app entry. It includes component styles, the documented public utility vocabulary, and static utility classes used by catalogue examples and shipped recipes/templates; components work without a host reset, Tailwind processing or private-source scanning. It deliberately omits global preflight. This path does not generate arbitrary utility classes written in app source.
 
 **Tailwind v4 application utilities:** when the app authors Tailwind classes, process this application stylesheet through its Tailwind v4 build integration:
 
@@ -14,8 +14,27 @@
 
 Tailwind supplies app-generated utilities and its layered preflight; theme.css makes the semantic and structural vocabulary available to that compilation. No package-private source scan is required. The default layer order is `theme, base, components, utilities`. Keep app resets inside `@layer base`; unlayered universal/tag resets outrank layered package styles regardless of import order. Do not blanket-reset `[data-slot]`, which also belongs to third-party and app markup. Put intentional scoped app overrides after these imports. See [integration](integration.md) for an optional app-owned reset and provider setup.
 
+## Set the application canvas
 
-Themelia 2.0.5 requires the official `@base-ui/react ^1.9.0` npm peer alongside
+The host owns the document font, page background and inherited text color.
+After importing package styles, set them in the application's stylesheet:
+
+```css
+@layer base {
+  html { font-family: var(--font-sans); }
+  body { margin: 0; background: var(--background); color: var(--foreground); }
+}
+```
+
+These roles follow the active light/dark theme. They also give app markup and
+intentionally inherited copy a page foreground. Components keep their own
+essential fonts and box model; this host setup is independent of a reset or
+Tailwind build and adds no stylesheet entry or dependency. Painted card and
+popover surfaces still pair their own background/foreground roles.
+
+## Resolve the installed package
+
+Themelia 2.0.6 requires the official `@base-ui/react ^1.9.0` npm peer alongside
 React, React DOM and Lucide. An app already using `^1.9.0` can retain that range.
 Remove any older private Base UI archive pin or override before refreshing the
 lockfile; dismissal translations and nested popup focus belong to Themelia's
@@ -107,27 +126,51 @@ each page or surface keeps one.
 
 ## Copy the complete skill bundle
 
-The package ships four focused capabilities, one compatibility/shared root and one agent definition. One copy of API/token/contract metadata, scripts and examples is shared by all three. Do not copy only an individual SKILL.md or duplicate the generated indexes into each skill.
+The package ships four focused capabilities, one compatibility/shared root and one agent definition. One copy of API/token/contract metadata, scripts and examples is shared by all four. Do not copy only an individual SKILL.md or duplicate the generated indexes into each skill.
 
-When the user requests installation, run the bundled copy helper with their configured agent skills directory. For Codex the usual destination is `~/.codex/skills`; honor a configured alternative:
+When the user requests installation, run the bundled copy helper with their configured agent skills directory. Codex supports project `.agents/skills` and user `~/.agents/skills`; honor an existing configured alternative:
 
 ```sh
-node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --copy --destination "$HOME/.codex/skills"
-node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --check --destination "$HOME/.codex/skills"
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --copy --destination .agents/skills
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --check --destination .agents/skills
 ```
 
 It copies `themelia-components`, `themelia-tokenization`, `themelia-composition`, `themelia-design`, and `themelia-react-ui-consumer` as real sibling directories. Rich templates are copied once under the shared directory. Markdown links are rebased for this installed layout; no symlinks or repository paths are required. Existing canonical/shared destinations are rejected before writing: preserve or move the previous complete bundle before an upgrade, then copy the release together. `--check` compares every expected asset after rebasing, so stale content with an unchanged development version is caught.
 
 ### Copy the designer agent
 
-`docs/consumer-skill/agents/themelia-ui-designer.md` is a Claude Code agent definition: a product designer that reads the records, writes a view spec, builds with public owners, renders 390 and 1440 wide in light and dark, scores the critique rubric and fixes. Its body reads skills and scripts through `node_modules/themelia-react-ui/...`, so it works wherever the skills were copied; other agents can follow it as a prompt. When the user requests it, copy it into the project's agents directory with the skills or on its own:
+`docs/consumer-skill/agents/themelia-ui-designer.md` is a Markdown agent definition and portable prompt: a product designer that reads records, writes a view spec, builds with public owners, renders 390 and 1440 wide in light and dark, scores the critique rubric and fixes. `review` mode is read-only. Its body reads skills and scripts through `node_modules/themelia-react-ui/...`, so it works wherever the skills were copied. The copy inside the shared skill is a reference; registering a custom agent depends on the host:
+
+| Host | Discoverable custom agent | Installer behavior |
+| --- | --- | --- |
+| Claude Code | `.claude/agents/themelia-ui-designer.md` | A destination ending in `.claude/skills` also copies/checks the sibling agent. `--no-agents` opts out; `--agents <dir>` overrides it. |
+| Antigravity | `.agents/agents/themelia-ui-designer.md` | Pass `--agents .agents/agents` explicitly with `.agents/skills`. |
+| Codex | `.codex/agents/<name>.toml` | The Markdown file remains a prompt/reference; this helper does not generate or register a Codex TOML agent. Follow the prompt directly or pass it to an available subagent. |
+
+`.agents/skills` is shared by multiple hosts, so the installer does not infer a Markdown-agent destination from it. See the official [Claude Code subagent](https://code.claude.com/docs/en/sub-agents), [Antigravity subagent](https://antigravity.google/docs/subagents), [Codex subagent](https://learn.chatgpt.com/docs/agent-configuration/subagents) and [skill metadata](https://learn.chatgpt.com/docs/build-skills) documentation. `agents/openai.yaml` is optional skill metadata, separate from custom agent registration.
+
+For Claude Code, copy the complete bundle and agent together:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --copy --destination .claude/skills
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --check --destination .claude/skills
+```
+
+For Antigravity, choose the agent destination explicitly:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --copy --destination .agents/skills --agents .agents/agents
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --check --destination .agents/skills --agents .agents/agents
+```
+
+An agent-only copy remains supported:
 
 ```sh
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --copy --agents .claude/agents
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --check --agents .claude/agents
 ```
 
-An existing `themelia-ui-designer.md` is never overwritten; move it before copying a newer release. Other agent files are left untouched.
+An existing `themelia-ui-designer.md` is never overwritten; move it before copying a newer release. Other agent files are left untouched. Combined copies preflight both destinations before writing; a conflict leaves the other destination untouched. Use the same destination/opt-out flags for `--check` that you used for copying.
 
 The package retains `docs/consumer-skills/themelia-foundation/SKILL.md` and `themelia-forms/SKILL.md` as compatibility routers. They are not added by fresh copying. Existing legacy or unrelated skills are left untouched; review older agent routing separately when upgrading. Keep app policy outside the copied package bundle.
 

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

@@ -68,6 +68,18 @@ icon mode; its search button expands and focuses the field. Current
 matching chooses the most-specific href and exposes ancestor state separately
 to custom item renderers.
 
+Pass the committed route as `currentUrl` so an open AppSidebar drawer closes
+after navigation. SidebarNavigationRail falls back to its controlled `value`
+when no URL is supplied. Use `closeDrawerOnNavigate={false}` on either owner
+to keep its drawer open, or handle the proposal through
+`onMobilePanelChange` when the provider's `mobilePanel` is controlled.
+For SideNav, pass the app's pathname as `currentPath` on the server and
+client and forward `aria-current` from its `renderLink` adapter.
+
+`Header` and `HeaderBreadcrumbs` also work in standalone and stacked shells.
+They show the built-in sidebar trigger and divider when a sidebar provider is
+present. `HeaderBreadcrumbs` accepts a custom `triggerSlot` in either layout.
+
 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`.
@@ -151,4 +163,15 @@ not evidence of an independent agent choosing the same composition.
 
 ## Form transport and router adapters
 
-Use [RHF workflows](rhf-workflows.md#transport-lifecycle) for frontend state with Inertia callback visits or TanStack async mutations. Await the complete transport before resetting dirty state or closing an overlay. The framework stays in the app. `renderLink` on AppSidebar/Page headers adapts the app router: forward href, children, className, accessible/native attributes and onClick; preserve modifier/new-tab behavior and invoke the supplied click handler so mobile navigation can close. Use the [typed shell recipe](../examples/app-layout.tsx) for the exact public renderLink type rather than inventing a router prop. React Router Link, Inertia Link and TanStack Link each need an app adapter matching their own installed version.
+Use [RHF workflows](rhf-workflows.md#transport-lifecycle) for frontend state with Inertia callback visits or TanStack async mutations. Await the complete transport before resetting dirty state or closing an overlay. The framework stays in the app. For a `renderLink` router adapter, forward href, children, className, accessible/native attributes and onClick. Preserve modifier and new-tab behavior. Pass the updated route to AppSidebar after navigation so it can close its open drawer. The [typed shell recipe](../examples/app-layout.tsx) uses the public renderLink type.
+
+Wrap compound controls directly in `FormField` to associate the visible
+caption and supporting text. Inline time, dimension, coordinate and key/value
+fields expose a named group. Popover time and upload fields name the picker
+control. RichTextEditor carries the same association into HTML source mode.
+
+Use `value`, `defaultValue` and `onValueChange` for Combobox and
+AsyncResourceCombobox. MultiCombobox uses the plural forms. The older
+`selectedValue` and `selectedValues` bindings still work. Use
+`defaultSearchValue` and `defaultOpen` for initial state, or pass
+`searchValue` and `open` to control it.

package/docs/consumer-skill/references/public-api.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "discoveryVersion": 1,
   "package": "themelia-react-ui",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "stylesheets": [
     "themelia-react-ui/style.css",
     "themelia-react-ui/theme.css",
@@ -2329,14 +2329,14 @@
       "layer": "base",
       "responsibility": "Base family: Card checkbox group; Card radio group; Checkbox; Choice inputs overview; List radio group; Pill radio group; Select; Switch; Switch card; Toggle field.",
       "jobs": [
+        "CardCheckboxGroup selects multiple values from comparable options whose labels and descriptions benefit from card targets, including a small two-option set.",
+        "SwitchCard gives one boolean setting a label, supporting description and clickable card-shaped target.",
         "The user picks from a known set of options, including a binary on/off.",
-        "Use Card checkbox group in an admin interface.",
         "Use Card radio group in an admin interface.",
         "Use Checkbox in an admin interface.",
         "Use List radio group in an admin interface.",
         "Use Pill radio group in an admin interface.",
         "Use Select in an admin interface.",
-        "Use Switch card in an admin interface.",
         "Use Switch in an admin interface.",
         "Use Toggle field in an admin interface."
       ],
@@ -2403,12 +2403,39 @@
         },
         {
           "title": "Card checkbox group",
-          "description": "Multi-select visual choices rendered as cards.",
-          "chooseWhen": [],
-          "avoidWhen": [],
+          "description": "CardCheckboxGroup selects multiple values from comparable options whose labels and descriptions benefit from card targets, including a small two-option set.",
+          "chooseWhen": [
+            "CardCheckboxGroup selects multiple values from comparable options whose labels and descriptions benefit from card targets, including a small two-option set."
+          ],
+          "avoidWhen": [
+            "A single boolean setting needs SwitchCard, ToggleField, Switch or Checkbox.",
+            "Unrelated flags have independent meaning and lifecycle; give each its own boolean control."
+          ],
           "appOwned": [],
+          "composition": {
+            "mappings": [
+              {
+                "symbol": "CardCheckboxGroup",
+                "roles": [
+                  "multiple-choice"
+                ],
+                "kind": "content",
+                "placement": "region",
+                "surface": "self"
+              }
+            ],
+            "owns": [
+              "Option-card targets, selection markers and responsive columns",
+              "Selected-values array and controlled/uncontrolled interaction"
+            ],
+            "parentOwns": [
+              "Comparable option records and selected value keys",
+              "onValueChange persistence, validation and domain meaning"
+            ],
+            "embedded": "Choose from the domain value shape and option meaning rather than an arbitrary minimum count. A filtered or permission-limited real choice set can contain one item."
+          },
           "jobs": [
-            "Use Card checkbox group in an admin interface."
+            "CardCheckboxGroup selects multiple values from comparable options whose labels and descriptions benefit from card targets, including a small two-option set."
           ],
           "tags": [
             "base",
@@ -2436,7 +2463,9 @@
               ]
             }
           ],
-          "alternatives": []
+          "alternatives": [
+            "themelia-react-ui/base/choice-inputs"
+          ]
         },
         {
           "title": "Card radio group",
@@ -2662,12 +2691,39 @@
         },
         {
           "title": "Switch card",
-          "description": "Prominent card-shaped boolean setting with supporting copy and icon.",
-          "chooseWhen": [],
-          "avoidWhen": [],
+          "description": "SwitchCard gives one boolean setting a label, supporting description and clickable card-shaped target.",
+          "chooseWhen": [
+            "SwitchCard gives one boolean setting a label, supporting description and clickable card-shaped target."
+          ],
+          "avoidWhen": [
+            "A dense form needs a compact Switch, Checkbox or ToggleField.",
+            "The value is a selection of items from a comparable option set; use a choice group."
+          ],
           "appOwned": [],
+          "composition": {
+            "mappings": [
+              {
+                "symbol": "SwitchCard",
+                "roles": [
+                  "boolean-setting"
+                ],
+                "kind": "content",
+                "placement": "region",
+                "surface": "self"
+              }
+            ],
+            "owns": [
+              "Framed setting row and accessible control label",
+              "Single-toggle pointer and keyboard interaction"
+            ],
+            "parentOwns": [
+              "Boolean value/defaultValue and onValueChange callback",
+              "Persistence, disabled and validation state"
+            ],
+            "embedded": "Use the boolean value channel directly; no one-element selected-values array or duplicate outer field label is needed."
+          },
           "jobs": [
-            "Use Switch card in an admin interface."
+            "SwitchCard gives one boolean setting a label, supporting description and clickable card-shaped target."
           ],
           "tags": [
             "base",
@@ -2695,7 +2751,9 @@
               ]
             }
           ],
-          "alternatives": []
+          "alternatives": [
+            "themelia-react-ui/base/choice-inputs"
+          ]
         },
         {
           "title": "Toggle field",
@@ -3957,6 +4015,7 @@
         "EmptyTitleProps",
         "ErrorState",
         "ErrorStateProps",
+        "ErrorStateStrings",
         "ErrorStateVariant",
         "LoadingState",
         "LoadingStateProps",
@@ -3974,6 +4033,7 @@
         "ProgressTrackProps",
         "ProgressValue",
         "ProgressValueProps",
+        "defaultErrorStateStrings",
         "defaultProgressStrings"
       ],
       "optionalPeers": [],
@@ -4377,13 +4437,13 @@
         "A label, editable control, and hint or error form one accessible field row.",
         "Build an application-owned validated form with consistent field and action presentation.",
         "Editable values need canonical field controls, field chrome, grouped choices, uploads, or form-state recipes.",
+        "FormActionsBar gives a multi-section form a full-width footer with leading status and trailing actions, optionally sticky to its scrolling ancestor.",
         "Related form fields need one titled section with optional actions and footer.",
+        "SubmitStateButton submits a form with a pending state and optional pristine protection through submitting, dirty and disableWhenPristine.",
         "Use Controlled form field in an admin interface.",
         "Use Dirty state banner in an admin interface.",
         "Use Error summary in an admin interface.",
-        "Use Form actions bar in an admin interface.",
-        "Use Operation password form in an admin interface.",
-        "Use Submit state button in an admin interface."
+        "Use Operation password form in an admin interface."
       ],
       "tags": [
         "base",
@@ -4572,12 +4632,46 @@
         },
         {
           "title": "Form actions bar",
-          "description": "Responsive leading and trailing action chrome for form workflows.",
-          "chooseWhen": [],
-          "avoidWhen": [],
+          "description": "FormActionsBar gives a multi-section form a full-width footer with leading status and trailing actions, optionally sticky to its scrolling ancestor.",
+          "chooseWhen": [
+            "FormActionsBar gives a multi-section form a full-width footer with leading status and trailing actions, optionally sticky to its scrolling ancestor."
+          ],
+          "avoidWhen": [
+            "A padded Card or FormSection footer already owns the inset and divider; pass action buttons directly to that footer.",
+            "A compact form needs only a local SubmitStateButton beside its fields."
+          ],
           "appOwned": [],
+          "composition": {
+            "mappings": [
+              {
+                "symbol": "FormActionsBar",
+                "roles": [
+                  "form-actions"
+                ],
+                "kind": "content",
+                "placement": "region",
+                "surface": "self",
+                "slots": [
+                  "leading",
+                  "trailing",
+                  "children"
+                ]
+              }
+            ],
+            "owns": [
+              "Top divider, opaque background and shared surface inset",
+              "Parent-width action wrapping and optional sticky positioning",
+              "Leading status and trailing actions; trailing takes precedence over children"
+            ],
+            "parentOwns": [
+              "Native form, validation and submission lifecycle",
+              "Action buttons and pending, dirty, cancel and accepted state"
+            ],
+            "page": "Place at the end of the form. In Card padding=\"none\", use flat FormSections with ordinary body insets followed by this edge-to-edge bar.",
+            "embedded": "Card.footerSlot and FormSection.footer already own footer geometry. Put SubmitStateButton or an action row directly in those slots; review custom hosts before nesting another bar."
+          },
           "jobs": [
-            "Use Form actions bar in an admin interface."
+            "FormActionsBar gives a multi-section form a full-width footer with leading status and trailing actions, optionally sticky to its scrolling ancestor."
           ],
           "tags": [
             "base",
@@ -4609,7 +4703,10 @@
               ]
             }
           ],
-          "alternatives": []
+          "alternatives": [
+            "themelia-react-ui/base/cards",
+            "themelia-react-ui/base/forms"
+          ]
         },
         {
           "title": "Form field",
@@ -4694,7 +4791,7 @@
               "Gaps between separate form subjects"
             ],
             "page": "Use ordinary section insets in an unpadded page or layout region.",
-            "embedded": "Inside a padded Card, use surface=\"flat\" padding=\"none\" so the parent supplies the single inset."
+            "embedded": "Inside a padded Card, use surface=\"flat\" padding=\"none\" so the parent supplies the single inset. A flat section in a zero-padding Card keeps its ordinary body inset. Choose each section from its own parent; do not flatten independent page sections to match an embedded sibling."
           },
           "jobs": [
             "Related form fields need one titled section with optional actions and footer."
@@ -4769,12 +4866,42 @@
         },
         {
           "title": "Submit state button",
-          "description": "Submit control that resolves loading and pristine form states.",
-          "chooseWhen": [],
-          "avoidWhen": [],
+          "description": "SubmitStateButton submits a form with a pending state and optional pristine protection through submitting, dirty and disableWhenPristine.",
+          "chooseWhen": [
+            "SubmitStateButton submits a form with a pending state and optional pristine protection through submitting, dirty and disableWhenPristine."
+          ],
+          "avoidWhen": [
+            "The command does not submit a form; use Button with an explicit type and callback."
+          ],
           "appOwned": [],
+          "composition": {
+            "mappings": [
+              {
+                "symbol": "SubmitStateButton",
+                "roles": [
+                  "form-submit"
+                ],
+                "kind": "content",
+                "placement": "region",
+                "surface": "none",
+                "slots": [
+                  "children"
+                ]
+              }
+            ],
+            "owns": [
+              "Button geometry, pending state and default submit type",
+              "Default primary tone and optional pristine disabling"
+            ],
+            "parentOwns": [
+              "Native form association, validation and async transport",
+              "submitting and dirty state; accepted values and error feedback"
+            ],
+            "page": "Keep the submit with its task-local form. Independent forms can each own a primary submit; a single full-page editor can deliberately use one header submit.",
+            "embedded": "Use directly in Card.footerSlot or FormSection.footer, or in FormActionsBar trailing. The pending prop is submitting, not loading."
+          },
           "jobs": [
-            "Use Submit state button in an admin interface."
+            "SubmitStateButton submits a form with a pending state and optional pristine protection through submitting, dirty and disableWhenPristine."
           ],
           "tags": [
             "base",
@@ -4802,7 +4929,10 @@
               ]
             }
           ],
-          "alternatives": []
+          "alternatives": [
+            "themelia-react-ui/base/buttons",
+            "themelia-react-ui/base/forms"
+          ]
         },
         {
           "title": "Validated form",
@@ -4877,7 +5007,6 @@
             "ControlledFormField",
             "DirtyStateBanner",
             "ErrorSummary",
-            "FormActionsBar",
             "SubmitStateButton"
           ],
           "references": [
@@ -11013,6 +11142,9 @@
         "formatMetricValue",
         "resolveTrend"
       ],
+      "deprecated": {
+        "MetricColorScheme": "Use the shared semantic tone through the tone prop."
+      },
       "optionalPeers": [
         "recharts"
       ],
@@ -11252,14 +11384,14 @@
             ],
             "owns": [
               "Chart title and footer anatomy",
-              "ChartContainer configuration and content region"
+              "ChartContainer around children with the required config; do not add a duplicate container"
             ],
             "parentOwns": [
               "Surface framing and insets unless explicitly enabled",
-              "Page or dashboard placement"
+              "Page/dashboard placement, series, axes and legend or direct labels"
             ],
-            "page": "Place chart subjects in a Grid or layout column with deliberate peer gaps.",
-            "embedded": "Keep the default card-free presentation inside an existing Card; opt into a surface at the composition boundary."
+            "page": "Place chart subjects in a Grid or layout column with deliberate peer gaps. Bind series to config keys through var(--color-<key>); multi-series charts can use ChartLegend with ChartLegendContent inside the Recharts chart or accessible direct labels.",
+            "embedded": "Keep the default card-free presentation inside an existing Card; opt into a surface at the composition boundary. Footer is supporting caption/actions; substantial tables and disclosures belong in a peer or body region rather than the chart footer."
           },
           "jobs": [
             "A custom chart needs shared title, description, action and footer regions."
@@ -18221,6 +18353,9 @@
         "useMentions",
         "useMentionsSearch"
       ],
+      "deprecated": {
+        "splitHtmlByMentions": "Render mentions within the original HTML tree with MentionContent."
+      },
       "optionalPeers": [],
       "layer": "features",
       "responsibility": "Features family: Mentions.",
@@ -18269,7 +18404,8 @@
               "symbols": [
                 "MentionInlineSuggestions",
                 "MentionPicker",
-                "MentionChip"
+                "MentionChip",
+                "MentionContent"
               ]
             }
           ],
@@ -19517,7 +19653,8 @@
             {
               "title": "API",
               "symbols": [
-                "RichTextEditor"
+                "RichTextEditor",
+                "FormRichTextEditor"
               ]
             }
           ],
@@ -19750,6 +19887,7 @@
         "CellValueKind",
         "CellValueProps",
         "CellValueTuple",
+        "ColumnDef",
         "ColumnFiltersHandler",
         "ColumnGroup",
         "ColumnVisibilityHandler",