themelia-ui 3.1.0 → 3.2.0

package/docs/learn/forms.md

@@ -69,9 +69,10 @@ consumer on plain state never resolves react-hook-form.
 
 ## Field chrome
 
-`FormField` renders exactly **one** supporting line, resolved as `error || helperText ||
-hint`. They replace each other rather than stacking, so a field never grows or shifts as
-validation state changes. It also owns the wiring: it associates the label, points
+`FormField` renders at most **one** supporting message, resolved as `error || helperText ||
+hint`. They replace each other rather than stacking. A message can wrap, and adding or
+changing it can change field height; check long translated errors at narrow widths.
+It also owns the wiring: it associates the label, points
 `aria-describedby` at the supporting line, and sets `aria-invalid` on the control when there
 is an error, without overriding any of these that the caller set explicitly. Errors are
 announced politely (`role="status"`), so validation firing on each keystroke does not
@@ -80,6 +81,25 @@ interrupt typing.
 `FieldGroup` covers several controls sharing one label and one supporting line — a date
 range, a name split in two.
 
+## Sections and completion
+
+Use FormSection for an editable region inside a form, Card for an independent subject,
+and ContentBlock for supporting read-only prose. Flat FormSections retain region padding;
+an enclosing Stack can use `gap="none"` when that padding supplies the desired separation.
+FieldGroup supplies fieldset/legend semantics. Each child FormField still needs a distinct
+label. A section heading is not a field label.
+
+A resolved promise is not evidence that validation succeeded. ActionDialog normally closes
+after its confirmation callback resolves. Set `closeOnAsyncComplete={false}` when the app
+resolves with errors, and close controlled `open` only after explicit success. For a native
+form, use `formId` to associate the dialog's submit action with that form; avoid also invoking
+the mutation in `onConfirm`. Native constraint validation, the submit handler and domain
+validation then each have one owner. Prevent duplicate submissions while pending, retain
+drafts after rejection and associate errors with the relevant field or root region.
+
+See the complete [multi-section form and nested action](./reference-workflows.md) sources.
+For the inset and gap contract, see [Structure and spacing](./structure-and-spacing.md#use-the-two-spacing-roles).
+
 ## Generated forms
 
 When the fields come from a schema at runtime, use `features/schema-form`. When they are

package/docs/learn/framework-wiring.md

@@ -22,7 +22,9 @@ cells. Write it once:
 import type { LinkRenderer } from "themelia-ui/layout/sidebar"
 
 export const renderLink: LinkRenderer = ({ href, children, active, disabled, external, ...rest }) =>
-  disabled || !href ? <span {...rest}>{children}</span> : <AppLink to={href} {...rest}>{children}</AppLink>
+  disabled || !href ? <span {...rest}>{children}</span>
+    : external ? <a href={href} {...rest}>{children}</a>
+    : <AppLink to={href} {...rest}>{children}</AppLink>
 ```
 
 Return one element and spread the rest of the props onto it: they carry the class, the
@@ -50,6 +52,20 @@ async lifecycle; the application decides cache invalidation, retries, and error
 </ResourceIndexShell>
 ```
 
+## Lookup and navigation lifetimes
+
+Pass a stable `scopeKey` to ResourceCombobox, SuggestionsCombobox or useSuggestions when the lookup's workspace, locale or
+permission context changes. Changing callback identity alone does not refetch. A scope
+change aborts old work, hides old results/errors and refetches an eligible open query while
+retaining query, controlled value and open state. Late responses from an old scope cannot
+complete the current lookup. The app owns whether the selected id remains valid.
+
+Sidebar workspace disclosure keeps the mobile sheet open. A selected workspace marked
+`external: false` dismisses the sheet after selection; external destinations retain native
+target/rel behavior. Forward renderer props, including the click handler, to the real link.
+The app's router handles same-app addresses and preserves modifiers and new-tab gestures.
+See the [workspace reference](./reference-workflows.md).
+
 ## Permissions
 
 Resolve authorization before constructing actions. Omit an action the user cannot perform;
@@ -58,16 +74,28 @@ through the module's tooltip or description seam.
 
 ## Translation
 
-Supply user-facing package copy through each component's `strings` prop. Keep product copy
+Supply component-owned copy through the selected API's documented `strings` prop. Passive
+components whose copy comes from children need no strings object. Keep product copy
 in application data or children. The default objects are exported so a locale can start
 from the complete shape rather than guessing keys; see [Internationalization](./i18n.md).
 
 ## Server rendering and client boundaries
 
-Import server-pure formatting modules freely. Interactive modules carry their own
-`"use client"` boundary in the published entrypoint. Do not wrap the whole package in one
-client module: exact subpaths keep server-pure imports server-pure and optional peers
-isolated.
+Interactive and provider-dependent entrypoints carry `"use client"`, including
+`themelia-ui/primitives` and `themelia-ui/ui-provider`; passive modules such as
+`themelia-ui/base/structure` can remain server-pure. Inspect the exact published entrypoint
+rather than inferring its boundary from its name. In a React Server Components framework, a server component
+can render those client components with serializable props; callbacks, hooks and live
+controlled state belong in an application client component. A provider can receive server
+rendered children, so keep the boundary around the interactive region rather than the whole
+page. Check your framework's serialization rules for config containing functions or modules.
+
+Formatting helpers exported from `primitives` share its client boundary: do not call them
+from an RSC server component as if they came from a server-pure subpath. Format server data
+with the application's server utilities or render the corresponding display primitive.
+`themelia-ui/theming` exports pure derivation helpers without a client directive. Exact
+subpaths also keep optional peers isolated. Ordinary Node SSR can load and render the
+component modules; that does not make their exports server-callable in RSC.
 
 For CSP, portals, nested theme regions, and defaults, use
 [Provider and scoping](./provider-and-scoping.md). Do not recreate provider context in an

package/docs/learn/i18n.md

@@ -5,8 +5,10 @@ overridable, and nothing in it inspects `navigator.language` or imports a transl
 
 ## Strings
 
-Each module exports a `*Strings` interface and a `default*Strings` object, and its
-components take a `strings` prop:
+Components that own visible or accessible copy document a `strings` prop; their modules
+export the matching `*Strings` interface and `default*Strings` object. Passive structures
+and components whose copy comes entirely from children need no strings object. Read the
+selected API rather than adding `strings` by analogy:
 
 ```tsx fragment — shape only, not a program
 <Copyable strings={{ copy: "Kopieren", copied: "Kopiert" }} value={apiKey} />

package/docs/learn/installation.md

@@ -4,8 +4,9 @@
 npm install themelia-ui
 ```
 
-React 19 and `react-dom` are required peers. Everything else is optional and only pulled in
-by the module that needs it; see [Optional peers](#optional-peers).
+React 19 and `react-dom` are required peers. The package's regular dependencies install
+automatically; additional peer packages are optional and resolved only by the modules
+that need them. See [Optional peers](#optional-peers).
 
 ## Browser support
 
@@ -107,8 +108,8 @@ releases.
 
 ## Optional peers
 
-Every peer other than React is optional, and each is reachable only from the modules that
-use it: a consumer who never imports `features/map` never resolves Leaflet.
+Every peer other than `react` and `react-dom` is optional, and each is reachable only from
+the modules that use it: a consumer who never imports `features/map` never resolves Leaflet.
 
 The peer-to-module table is in [`docs/generated/imports.md`](../generated/imports.md).
 

package/docs/learn/migration.md

@@ -3,6 +3,25 @@
 What changes between versions, what to do when you upgrade, and which changes a stable major
 allows.
 
+## Upgrading to 3.2
+
+3.2 adds consumer diagnostics, complete reference workflows and optional `scopeKey` support
+for asynchronous combobox lookups, alongside responsive grid, dialog and navigation fixes.
+Applications already on 3.1 need no new codemod replacements. Applications upgrading from
+3.0 or earlier must also follow [Upgrading to 3.1](#upgrading-to-31).
+
+After updating the package, refresh the installed consumer skill with the
+[packaged installer](./verification.md#offline-diagnosis-and-skill-freshness). Review any
+local edits before replacing them, then run the read-only diagnostics and your application's
+type, build and interaction checks. The [structural guide](./structure-and-spacing.md),
+[blocks guide](./blocks.md) and [complete workflows](./reference-workflows.md) describe the
+public composition contracts.
+
+For lookups whose results depend on a workspace, tenant or similar context, pass a stable
+`scopeKey` that changes with that context. The lookup aborts and invalidates old responses;
+the application still owns clearing a selection or query that is no longer valid. See the
+[scoped resource selection workflow](./reference-workflows.md).
+
 ## Upgrading to 3.1
 
 3.1 renames and removes public API as well as adding to it. Upgrade deliberately, not
@@ -83,8 +102,9 @@ selects `[data-row-density]`, `[data-media-density]` or `[data-activity-density]
 colour a `light-dark(light, dark)` pair. For a theme of your own:
 
 - Declare it on `:root` alone. The selector list 3.0 asked for (`:root, [data-ui-scope],
-  [data-density], [data-theme], .light, .dark`) is not needed: nothing below `:root` declares a
-  theme variable again.
+  [data-density], [data-theme], .light, .dark`) is not needed: component styles inherit the
+  root defaults. Explicit regional overrides and density presets replace their corresponding
+  inherited values; set a preset-specific spacing override on that preset.
 - Write a dark value into the colour's pair, `--primary: light-dark(#2563eb, #60a5fa)`, rather
   than a `.dark { … }` block, which colours a dark page but misses a dark region inside a light
   one.

package/docs/learn/provider-and-scoping.md

@@ -1,5 +1,11 @@
 # Provider and scoping
 
+Choose one document density owner, then use UIScope for a deliberately different region.
+Changing density changes spacing; keep primary copy in Text and headings in Heading or their
+component owners. Check the last field/next heading together: CardContent, FormSection and
+Stack can each contribute separation. A portal must stay inside its intended token scope;
+UIPortalHost provides that boundary. Test open popups as well as the page beneath them.
+
 Three components, and the difference between them is what they are allowed to touch.
 
 | | Renders | Reaches | Use for |
@@ -71,8 +77,10 @@ value, and a value is replaced, not merged.
 
 That is the configuration components read, and the CSS follows it: each scope writes the
 merged overrides on its element, so inside the nested scope above `--primary` is red and
-`--secondary` is green. Nothing below `:root` declares a theme variable again, so every value
-inherits through any element, a `Scope` or a `data-density` region included; see
+`--secondary` is green. Component styles inherit global tokens rather than redeclaring
+theme defaults. Explicit Scope/UIScope overrides replace inherited values; a density preset
+also resets its spacing and control heights on that region. A value outside that boundary
+does not override its local declaration; see
 [Theming](./theming.md#setting-a-theme).
 
 ## Scope — tokens only
@@ -85,17 +93,18 @@ inherits through any element, a `Scope` or a `data-density` region included; see
 </Scope>
 ```
 
-`Scope` renders a `div` without layout. `render` picks another element, as on every
-component (`render={<section />}`), and `transparent={false}` gives it a box. Every
+`Scope` renders a `div` without layout. Its `render` prop picks another element
+(`render={<section />}`), and `transparent={false}` gives it a box. Every
 component inside reads the variables it sets, because components compute from the theme where
 they use it; any element with a `style` does the same, and `Scope` only adds the missing
 layout rule and the `data-ui-scope` marker.
 
 ## Portals and scopes
 
-A scope works through CSS custom properties and the `[data-density]` / `[data-theme]`
-attribute selectors, and both inherit down the DOM subtree. A portal renders elsewhere in the
-document, so by default neither follows it:
+A scope uses CSS custom properties; its `data-density` and `data-theme` attributes establish
+spacing and colour-scheme values that inherit through the DOM subtree. The attributes
+themselves are not copied to descendants. A portal renders elsewhere in the document, so
+those inherited values do not follow it by default:
 
 ```tsx fragment — a template with a hole in it
 <UIScope config={{ density: "compact" }}>
@@ -136,7 +145,7 @@ in — a shadow root, or a positioned overlay element it manages itself.
 
 ## Strict Content Security Policy
 
-Some Base UI-backed controls emit a tiny inline style or pre-hydration script for behavior
+Some Base UI-backed controls emit a tiny inline style element or pre-hydration script for behavior
 the component stylesheet cannot express. Put `CSPProvider` at the same application boundary
 as `UIRoot` and pass the request nonce through:
 
@@ -154,7 +163,7 @@ React 19 hoists styles that carry `precedence`. During streaming SSR, configure
 renderer with the same style nonce as the provider; otherwise React omits the attribute and
 warns about the mismatch.
 
-When the policy permits no inline elements at all, suppress Base UI's style elements and
+When the policy forbids inline style elements, suppress Base UI's style elements and
 ship the scrollbar rule in the consuming application's stylesheet:
 
 ```tsx fragment — App comes from the consuming application
@@ -171,6 +180,15 @@ ship the scrollbar rule in the consuming application's stylesheet:
 `disableStyleElements` does not disable kit behavior; it moves those small rules into the
 consuming app. It does not change how the kit's CSS loads.
 
+This option does not remove inline scripts or `style` attributes. A nonce authorizes the
+matching style/script elements; it does not authorize style attributes in server-rendered
+HTML. Providers, responsive structure and popup positioning can use style attributes, so
+a policy that blocks them needs a separate SSR strategy for the adopted components.
+Inspect the rendered HTML and browser CSP reports; `disableStyleElements` alone does not
+establish compatibility with that policy. See the
+[Base UI CSP reference](https://base-ui.com/react/utils/csp-provider#inline-style-attributes)
+for the distinction and available integration strategies.
+
 ## Reading the config
 
 Resolution, in every component:

package/docs/learn/reference-workflows.md

@@ -0,0 +1,43 @@
+# Complete reference workflows
+
+These sources use public package imports and fixed local mock operations. Copy the complete
+workflow directory, including relative helpers, then replace its transport and policy with
+your application's. The [versioned inventory](../generated/workflows/index.json) lists every
+file, import and API reference. Its package version must match the installed package.
+
+| Workflow | Owners and application seam | Complete entry source |
+| --- | --- | --- |
+| Record detail | Page owns route heading; sibling Cards own subjects; MetadataList owns facts; app owns record commands | [Record detail](../generated/workflows/record-detail/page-layout/record-detail-reference.tsx) |
+| Server resource index | DataView owns browser presentation; app owns server matching, unknown totals, cursor and page selection | [Resource index](../generated/workflows/resource-index/data-view/resource-index-reference.tsx) |
+| Multi-section form | Card owns surface; flat FormSections retain insets; FieldGroup and FormField own names; app owns validation and completion | [Form](../generated/workflows/multi-section-form/form-workflow/multi-section-reference.tsx) |
+| Scoped resource selection | ResourceCombobox owns lookup; app owns scopeKey and selection validity; Overlay owns task | [Selector](../generated/workflows/scoped-resource-selection/combobox/scoped-resource-reference.tsx) |
+| Nested action flow | Parent owns draft; child owns confirmation; app closes explicitly after successful mutation | [Nested action](../generated/workflows/nested-action-flow/action-overlays/nested-action-reference.tsx) |
+| Workspace navigation | Shell owns geometry; workspace owns disclosure; app owns router and same-app policy | [Workspace](../generated/workflows/workspace-navigation/app-shell/workspace-navigation-reference.tsx) |
+| Media picking | MediaLibraryDialog owns query/picking UI; app commits a separate picker draft on confirmation, pages through footer slots, hydrates saved ids independently, reports unavailable selection and authorizes fetches | [Media](../generated/workflows/media-picking/media-library/media-picking-reference.tsx) |
+| Communications overview | MetricGrid owns quantities; MetadataList owns prose facts; app owns period, delivery state and retry | [Communications](../generated/workflows/communications-overview/analytics/communications-reference.tsx) |
+| Website editor | RichTextEditor owns editing; app retains locale drafts and alt text; RichText sanitizes preview | [Website editor](../generated/workflows/website-content-editor/rich-text-editor/website-content-reference.tsx) |
+
+Forms using plain state need no form peer. The optional forms-rhf adapter connects existing
+React Hook Form state without duplicating it. The resource-index workflow uses features/table and
+needs its table peer; record-detail uses peer-free base/table; analytics and rich editing require the peers listed in their generated
+API pages. The general reference consumer stays free of optional peers; the admin reference
+consumer demonstrates adopted adapters.
+
+Pending, empty, failed refresh, unavailable selection and resolved validation errors are
+different states. These fixtures demonstrate local feedback and retained drafts. They do
+not establish real persistence, permissions, cache invalidation or backend sanitization.
+Exercise the named cases in your app; [record the evidence](./verification.md#completion-record)
+and identify conditions you could not inspect.
+
+The inventory's `verification` entries map required cases to behavioral tests or visual
+inspection conditions. They specify coverage to run, not a claim that your application passed.
+`repositoryFile` identifies a maintainer test in the source repository; copy workflow files
+from the inventory's generated source list and adapt the named behaviors to your test runner.
+The browser cases use explicit mock actions; the read-only observer supplies advisory geometry
+findings. Review screenshots and semantics separately in both themes and densities at mobile,
+desktop and wide widths, including long copy and RTL. Build/type checks prove the complete
+sources and public imports; rich-text security tests exercise the sanitization boundary.
+
+When embedding a contained app shell in an existing main landmark, use `contentRender={<div />}`
+so the composition keeps one main. For a shell that owns the application's main, omit that
+override. The reference uses the embedded form because it also appears inside a documentation page.

package/docs/learn/structure-and-spacing.md

@@ -0,0 +1,147 @@
+# Structure and spacing
+
+Choose the semantic owner first, then arrange its siblings. A Page owns route geometry;
+Card owns an independent subject; ContentBlock owns supporting content; FormSection owns
+an editable region. Stack and Grid arrange those owners without adding a heading, landmark,
+surface or inset. See [Composition](./composition.md#decide-the-owners-before-jsx) for names,
+commands and field ownership, and [Blocks](./blocks.md) for ready subject arrangements.
+
+## Choose a structural block
+
+| Need | Public owner | What it supplies |
+| --- | --- | --- |
+| Route title, description and commands | `Page` from `layout/page` | Container, page header and body rhythm. It does not create a main landmark or own scrolling. |
+| Page scroll inside a bounded shell | `PageViewport` from `layout/containers` | Scroll region and an inline-size query container. Focusable by default for keyboard scrolling. |
+| Centred width and inline gutter | `Container` from `layout/containers` | Width and gutter only. Page already includes it. |
+| Semantic section with rhythm between groups | `Section` from `layout/containers` | A native section and twice the group gap; supply its heading or accessible name. |
+| Primary work beside a secondary summary | `TwoColumnLayout` from `layout/containers` | Main/aside arrangement, optional full-width header/footer; stacks below `lg`. Aside stays second in the DOM. |
+| One row or column of passive siblings | `Stack` from `base/structure` | Direction, gap, alignment, distribution and optional wrapping. No padding prop. |
+| An explicit column count | `Grid` and `GridCell` from `base/structure` | One to four columns, responsive gaps and cell spans. |
+| As many equal columns as fit | `AdaptiveGrid` from `base/structure` | Auto-fit tracks; `minColumnWidth` is `default` (16rem), `sm` (12rem) or a CSS length. |
+| A fluid main region and a constrained rail | `Split` from `base/structure` | Two direct children: main first, side second. `sideWidth` defaults to 18rem; `collapseBelow` defaults to `md`. |
+| Intentional edge-to-edge content in an inset | `Bleed` from `base/structure` | Negative margins on the selected axis. Match `amount` to the inset it cancels. |
+
+Read the exact [structure API](../generated/components/base--structure.md),
+[containers API](../generated/components/layout--containers.md) and
+[page API](../generated/components/layout--page.md) before adding props. Container's
+`maxWidth` (`sm`, `md`, `lg`, `xl`, `2xl`, `full`) and `gutter` (`none`, `sm`, `md`, `lg`)
+are a different contract from Stack/Grid widths (`default`, `sm`, `full`, `none` or a CSS
+length). Container gutters are zero, one, one-and-a-half or twice `--padding`; they do not
+add spacing tokens. Stack/Grid `maxWidth` caps width without centring it or adding a gutter.
+
+An app shell normally owns the single main landmark and page scroller. Do not add another
+PageViewport around each section. For document scrolling without a bounded shell, Page can
+live in the application's existing main. When embedding a shell inside another main, use
+its documented `contentRender` seam; see [complete workflows](./reference-workflows.md).
+
+## Use the two spacing roles
+
+| Role | Public tokens | Typical use |
+| --- | --- | --- |
+| Container inset | `--padding` | Card regions and decorated ContentBlocks |
+| Item inset | `--padding-sm` | Rows, cells and compact items |
+| Between groups | `--gap`, `gap="default"` | Fields, sibling Cards, sections |
+| Within a group | `--gap-sm`, `gap="sm"` | Title/description, icon/label, toolbar controls |
+
+The omitted structure gap is `default`. `gap="none"` removes separation; it is not a third
+spacing step. Insets belong to the child surface and gaps to the parent arrangement. Avoid
+giving both the same separation job. Density changes these lengths together; it does not
+choose smaller text roles. [Theming](./theming.md#scale-and-density) explains density, scale
+and typography scale, including overriding a preset's values.
+
+CardContent supplies its inset and a group gap between direct children; it drops its top
+padding after an undivided CardHeader. Card `surface="flat"` removes decoration and retains
+region insets. FormSection is a Card composition, so a flat FormSection inside CardContent
+still adds its own inset. Use `Stack gap="none"` between such sections when their insets
+already supply the intended rhythm; do not assume flat means flush.
+
+ContentBlock is different: its default `surface="plain"` supplies heading/content spacing
+without an inset or frame. Its `bordered`, `muted` and `card` surfaces add an inset.
+`flush` drops that decorated surface's inset for children that own their own padding.
+Neither flat nor flush changes field associations or heading semantics.
+
+```tsx compile
+import { Card } from "themelia-ui/base/cards"
+import { ContentBlock, MetadataList } from "themelia-ui/base/display"
+import { Grid, Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { Page } from "themelia-ui/layout/page"
+import { TwoColumnLayout } from "themelia-ui/layout/containers"
+
+export function AccountOverview() {
+  return <Page header={{ title: "Account" }} maxWidth="lg">
+    <TwoColumnLayout
+      main={<Stack>
+        <Grid columns={{ base: 1, md: 2 }}>
+          <Card title="Contact" titleLevel={2}>
+            <MetadataList items={[{ id: "email", label: "Email", value: "alex@example.com" }]} />
+          </Card>
+          <Card title="Billing" titleLevel={2}>
+            <MetadataList items={[{ id: "status", label: "Status", value: "Active" }]} />
+          </Card>
+        </Grid>
+        <Card title="Notes" titleLevel={2}>
+          <ContentBlock description="Context for the next account review.">
+            <Text>The customer prefers email updates.</Text>
+          </ContentBlock>
+        </Card>
+      </Stack>}
+      aside={<Card title="Summary" titleLevel={2}><Text>Review due next month.</Text></Card>}
+    />
+  </Page>
+}
+```
+
+The example has one route heading, three independent subjects in the main region and a
+secondary summary. Page supplies the gutter; TwoColumnLayout supplies main/aside separation;
+Stack/Grid separate subjects; each Card supplies its inset. The complete record and form
+workflows add application-owned commands, validation and asynchronous states.
+
+## Know which width drives responsiveness
+
+A responsive structure prop accepts a single value or an object such as
+`gap={{ base: "sm", md: "default" }}`. Values carry forward until another named step replaces
+them; omitted lower steps use the component's defaults. `sm` as a gap value means the small
+gap; `sm` as an object key means a breakpoint.
+
+| Step | Viewport minimum | Grid's nearest query-container minimum |
+| --- | --- | --- |
+| `base` | All widths | All widths |
+| `sm` | 40rem | 24rem |
+| `md` | 48rem | 32rem |
+| `lg` | 64rem | 40rem |
+| `xl` | 80rem | 52rem |
+| `2xl` | 96rem | 64rem |
+
+Grid uses viewport steps when no ancestor establishes inline-size containment. With a query
+container, such as PageViewport or ContentBlock, Grid's columns, gaps, alignment and maximum
+width use the nearest container and the smaller thresholds above. Grid does not create its
+own query container. Stack, Split, Bleed, AdaptiveGrid's responsive gap/alignment and
+GridCell spans use viewport steps. AdaptiveGrid's **column count** always follows available
+width through auto-fit. TwoColumnLayout stacks below the viewport's `lg` step.
+
+Grid defaults to one column and two from `md`; `columns={1}` stays one at every width.
+Use `GridCell span="full"` for a full row at every width. Numeric spans must fit the current
+column count; `span={{ base: 1, md: "full", xl: 2 }}` can switch between numeric and full
+placement. Coordinate responsive spans with the Grid, especially inside a query
+container where their thresholds differ. Prefer AdaptiveGrid when the available panel width
+should decide the count without coordinating breakpoints. Visual side positioning in Split
+or TwoColumnLayout does not change reading or keyboard order.
+
+## Bleed, custom CSS and verification
+
+Bleed's default amount is `none` and its default axis is `inline`. An intentional image
+escape can use `amount="default"` inside an inset of `--padding`, or `sm` inside
+`--padding-sm`. The shipped spacing pairs have matching padding/gap values; a custom theme
+that separates those values must account for the actual inset. Bleed does not create a
+surface or crop media. Check edges and focus visibility in the surrounding surface.
+
+Application-specific geometry can use `className` and CSS over public tokens; use the
+documented props first. Do not target private `--_…` variables or CSS Module hashes. Keep
+copy in Text/Heading and field labels in FormField rather than setting local type styles.
+For product CSS, prefer logical properties so inline start/end follow RTL.
+
+Check a narrow **parent** as well as a narrow viewport, long headings and translated labels,
+both themes and densities, and keyboard access to the scroller. Verify that additional
+surfaces or gaps serve an independent subject. [Consumer verification](./verification.md)
+separates compiled examples, interaction evidence and visual inspection.

package/docs/learn/theming.md

@@ -3,7 +3,8 @@
 The theme is about eighty variables, declared once at `:root` in `src/styles/theme/`. Each
 colour holds both modes as `light-dark(light, dark)`, and every length, shadow, tint and
 duration comes as a pair. Components derive everything else where they use it, so a value
-you set anywhere reaches every component below it. [`src/styles/TOKENS.md`](../../src/styles/TOKENS.md)
+you set on a region reaches its descendants unless another scope or preset overrides it.
+[`src/styles/TOKENS.md`](../../src/styles/TOKENS.md)
 names the variable for each role.
 
 ## Setting a theme
@@ -22,7 +23,8 @@ for both modes:
 ```
 
 That one block reaches every region, including popups portalled to `<body>` and a dark
-region inside a light page: nothing below `:root` declares a colour again.
+region inside a light page. Component styles do not redeclare theme colour defaults;
+an explicit regional theme override takes precedence within that region.
 
 The same values work on any element, for a region of their own:
 
@@ -139,6 +141,8 @@ and headings fall back to the interface font.
 Compose title and description regions with CardHeader, ContentBlock or OverlayHeader, action
 regions with CardFooter or OverlayFooter, and label/value facts with MetadataList. These
 components own their spacing, so the application does not reproduce it.
+See [Structure and spacing](./structure-and-spacing.md) for the owner and responsive-width
+contracts before changing layout values.
 
 ## Scale and density
 

package/docs/learn/troubleshooting.md

@@ -1,5 +1,22 @@
 # Troubleshooting
 
+Before patching a shared component, trace its callers and inspect one representative of
+every affected surface. Recheck open portals, nested forms and small screens when shared
+spacing or naming changes. Use the [read-only diagnosis and completion record](./verification.md)
+to distinguish contract errors, advisory composition findings and unavailable coverage.
+
+## A lookup still shows another workspace
+
+Set `scopeKey` on ResourceCombobox, SuggestionsCombobox or useSuggestions. Callback identity is not an invalidation API.
+The key invalidates answers and errors while keeping query/open/value ownership; explicitly
+clear a selected id if it is invalid in the new scope. See the [complete selector](./reference-workflows.md).
+
+## Validation resolves but the dialog closes
+
+Set `closeOnAsyncComplete={false}` and close controlled `open` after successful validation
+and mutation. Use `formId` for native submission and keep one mutation owner. Nested child
+cancel/Escape should leave the parent draft visible; verify focus returns to the child invoker.
+
 ## A component is unstyled
 
 A component brings its own CSS in a bundler. When it arrives unstyled:
@@ -74,8 +91,8 @@ listed there, report it as a package containment defect.
 
 ## A theme or density override does not apply
 
-Every theme variable is declared once, at `:root`, and inherits from wherever you set it. When
-an override does not show:
+Theme defaults are declared at `:root` and inherit until an explicit scope override or
+density preset establishes another value. When an override does not show:
 
 - **Is it the theme's name?** A 3.0 name such as `--space-md`, `--control-h` or
   `--primary-10` is gone; the codemod renames or reports each one, and
@@ -121,6 +138,10 @@ set `disableStyleElements` and serve the documented Base UI behaviour rules from
 stylesheet. The kit's stylesheets are ordinary static CSS. See
 [Provider and scoping](./provider-and-scoping.md#strict-content-security-policy).
 
+If the report names `style-src-attr`, a nonce or `disableStyleElements` will not authorize
+server-rendered style attributes. Inspect the adopted components' SSR output and use the
+separate attribute-policy strategy described in that guide.
+
 In a bundled app the kit's CSS follows your own pipeline: stylesheet files in production,
 while a dev server or `style-loader` that injects `<style>` elements needs the nonce, as your
 own CSS does.
@@ -128,11 +149,13 @@ own CSS does.
 ## The design looks inconsistent after overrides
 
 Override global semantic tokens first: colour roles, radius, spacing and density,
-typography, and control geometry. Component-level variables are implementation detail
-unless the module reference describes one as an extension point. Do not target hashed CSS
+typography, and control geometry. Variables prefixed `--_` are private implementation detail.
+Use a component-level variable only when its module reference documents a public extension
+point. Do not target hashed CSS
 Module names; use the stable `data-slot` attributes and BEM hooks such as
 `{name}--component`, and for a state the attributes the primitives set (`data-open`, `data-checked`, `data-disabled`,
-`data-highlighted`, `data-popup-open`). Radix's `[data-state="open"]` matches nothing here.
+`data-highlighted`, `data-popup-open`). Do not assume Radix's `[data-state="open"]` for Base
+UI primitives. Use a module's own `data-state` only when its API documents that contract.
 
 ## Rich text and untrusted HTML
 

package/docs/learn/verification.md

@@ -32,8 +32,9 @@ test("global search returns focus after dismissal", async ({ page }) => {
 Prefer role- and name-based assertions over CSS Module selectors. When a visual or state
 assertion needs a DOM hook, use `data-slot`, documented BEM hooks, or the state attributes
 the primitives set (`data-open`, `data-checked`, `data-disabled`, `data-highlighted`,
-`data-popup-open`). These are Base UI's attributes, not Radix's: `[data-state="open"]`
-matches nothing.
+`data-popup-open`). Use Base UI's documented attributes for its primitive states rather
+than assuming Radix's `[data-state="open"]`. Some kit modules expose their own `data-state`
+contract; use it only where the selected API documents it.
 
 ## Theme contract check
 
@@ -41,6 +42,61 @@ Create one application fixture that changes primary colour, surface/background r
 radius, density, and typography scale at a scope boundary. If a component ignores it, report
 the module and token before adding a local patch: the package may be missing a derivation.
 
+## Offline diagnosis and skill freshness
+
+Run the commands from the package installed in this application:
+
+```bash
+node node_modules/themelia-ui/scripts/consumer/install-skill.mjs --project=. --check --json
+node node_modules/themelia-ui/scripts/consumer/diagnose.mjs --project=. --json src/
+```
+
+Both checks are read-only. Diagnostics use the consumer's installed TypeScript parser and
+the package's generated export/migration facts. Supply explicit paths. Unsupported formats,
+parse failures, missing paths, metadata or parser produce exit 2 (incomplete); definite
+contract errors produce exit 1; complete checks without errors produce exit 0. Advisory
+composition/private-style warnings do not establish a defect. Excluded build/dependency
+directories and symlinks are not followed. Reports name the checked and skipped rules/files.
+
+Freshness reports expected and installed versions plus missing, stale, modified or unmanaged
+copies. Review modifications before reinstalling a generated copy. The installer refuses local edits
+until `--overwrite-modified` explicitly replaces reviewed generated content. Keep application policy
+in a separate skill; an unmanaged same-name skill is preserved. Missing metadata requires
+repairing the package installation or consulting the matching release, never inventing an API.
+
+If an installed copy's manifest is missing or invalid, the installer repairs it automatically
+only when its remaining files match the packaged content. Differing or extra files require
+review and `--overwrite-modified`, just like edits to a copy with a valid manifest.
+
+Replacements are staged before writes, and caught write failures restore backups. An abrupt
+process termination can leave mixed versions across targets and sibling `.backup-*` or
+`.installing-*` directories. Run `--check`, review those retained directories, preserve any
+local policy, and reinstall the intended generated copies. A backup-cleanup error means the
+new copies were installed; the error names the retained backup for review and manual cleanup.
+
+The [browser observer](../build/browser-composition-fixture.ts) accepts an already open caller
+fixture and observes overflow, repeated sibling headings and control visibility. It performs
+no navigation, click or submission. These geometry/semantic observations are advisory; they
+do not establish accessibility or business acceptance. Optional browser tooling belongs in
+the application's test dependencies, not the UI runtime.
+
+Opt into interaction tests only against explicit mock actions. The [complete workflows](./reference-workflows.md)
+provide scoped late responses, pending/empty/error lists, nested cancel, resolved validation,
+workspace selection and retained locale drafts. Assert keyboard selection without accidental
+form submission, one Escape layer at a time, focus return, associated errors and explicit
+successful completion. Do not crawl unknown application routes or submit business forms.
+
+## Completion record
+
+Record installed package/skill versions; selected owners and seams; shared callers inspected;
+fixture routes and states; viewport widths; themes, densities and locales; keyboard/focus
+interactions; commands and observed results. Separate type/build evidence, behavior tests,
+visual inspection and application acceptance. Name unavailable conditions explicitly.
+
+When no browser is available, report types/build/static findings and mark interaction and
+visual checks unverified. Passing named static/browser checks does not establish permissions,
+data integrity, persistence, backend sanitization or every product workflow.
+
 ## Upgrade check
 
 Read the [changelog](../../CHANGELOG.md), run the package's codemod when a release names one