themelia-ui 2.0.1 → 3.1.0

package/.agents/skills/themelia-ui/references/migration.md

@@ -1,10 +1,180 @@
 # Compatibility and migration
 
-The package is `2.0.1`. The stable-major policy below applies within a major version.
+What changes between versions, what to do when you upgrade, and which changes a stable major
+allows.
+
+## Upgrading to 3.1
+
+3.1 renames and removes public API as well as adding to it. Upgrade deliberately, not
+through a caret range: pin `themelia-ui` to `~3.0.0` until you have run the codemod and fixed
+what TypeScript reports.
+
+**Blocks are published under `blocks/`.** The tier the documentation, the component index
+and the finder call Blocks now has subpaths that say so:
+
+| was | is |
+| --- | --- |
+| `themelia-ui/patterns/analytics` | `themelia-ui/blocks/analytics` |
+| `themelia-ui/patterns/onboarding` | `themelia-ui/blocks/onboarding` |
+| `themelia-ui/patterns/timelines` | `themelia-ui/blocks/timelines` |
+| `themelia-ui/admin/patterns/access` | `themelia-ui/blocks/admin/access` |
+| `themelia-ui/admin/patterns/commerce` | `themelia-ui/blocks/admin/commerce` |
+
+Module stylesheet subpaths are removed. Importing a component in a bundled app brings its CSS.
+
+**Components bring their own CSS.** In a bundled app, importing a component now brings its
+stylesheet, once, and a module you never import brings none. To upgrade:
+
+1. Run the codemod over each directory that holds application code: `src/`, and `app/` or
+   `.storybook/` where you have them.
+   It removes JavaScript imports of `themelia-ui/style.css` and of module stylesheets, which would
+   now load the CSS twice.
+2. The codemod removes obsolete module CSS `@import`s. Review any remaining stylesheet
+   references it reports. With Tailwind, keep `@import "tailwindcss"` and the bridge, and drop
+   `@import "themelia-ui/style.css"` or `@import "themelia-ui/core.css"` from the Tailwind entry.
+3. If the application renders on the server with Vite (Astro, React Router, TanStack Start, Vike),
+   list `themelia-ui`, and any installed package that imports it, in `ssr.noExternal`; Astro
+   renders the kit unstyled without it. See
+   [Server rendering with Vite](installation.md#server-rendering-with-vite).
+4. If your bundler config sets its own resolve conditions, keep `module` in them.
+5. Pages that link stylesheets without a bundler link `style.css`.
+
+**Fill style is `appearance`.** `tone` is colour, `appearance` is fill and `variant` is
+structure, on every component. TypeScript reports each rename:
+
+| was | is |
+| --- | --- |
+| `buttonStyle` on a Button, a Button-like component or an action definition | `appearance` |
+| `ButtonStyle`, `ActionButtonStyle` | `ButtonAppearance`, `ActionAppearance` |
+| `defaults: { button: { buttonStyle } }` | `defaults: { button: { appearance } }` |
+| `variant` on `Badge`, `Toggle` and `SidebarMenuButton` | `appearance` |
+| `BadgeVariant` | `BadgeAppearance` |
+| `badgeVariants({ tone, variant })` on your own element | `<Badge tone appearance render={<a … />}>` |
+| `badgeVariant` on a metadata badge value | `badgeAppearance` |
+| `confirmStyle` on an overlay or an action modality | `confirmAppearance` |
+
+Button renders `data-appearance` instead of `data-style`, and Toggle `data-appearance`
+instead of `data-variant`: update CSS that selects either.
+
+**Two steps for every size.** A size, padding or gap prop offers `default` and `sm`. `md` is
+`default`, which is also what leaving the prop out gives you; a step larger than the default
+is gone. The gaps map like this:
+
+| was | is |
+| --- | --- |
+| `gap="2xs"`, `"xs"`, `"sm"`, `"md"` | `gap="sm"` (8px) |
+| `gap="lg"`, `"xl"`, `"2xl"` | `gap="default"` (16px), or no `gap` |
+| no `gap` on a `Stack` or `Split` (8px) | 16px; write `gap="sm"` to keep 8px |
+
+Widths take `default`, `sm`, `full`, `none` or a CSS length such as `"48rem"`, and a free
+string no longer type-checks. `Slider` and `SliderField` lose `size`, `InputGroupButton`
+takes `iconOnly` instead of its icon sizes, and an action modality's `size`, which nothing
+read, is gone.
+
+**`density` belongs to the provider.** `MetadataList density="compact"` becomes
+`size="sm"`, `MediaLibrary density="compact"` becomes `size="sm"`, `ActivityFeed density`
+becomes `variant`, and `AiTask density="expanded"` becomes `defaultExpanded`. CSS that
+selects `[data-row-density]`, `[data-media-density]` or `[data-activity-density]` selects
+`[data-size]` or `[data-variant]`.
+
+`Text` drops `size="xxs"` and `weight="regular"`: write `xs` and `normal`.
+
+**The theme is one level.** It is about eighty variables, declared once at `:root`, each
+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.
+- 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.
+- The palette, the alpha steps, the spacing ladder, the control, icon and avatar ladders, the
+  derived role variables and the scale factors are gone. The codemod renames a variable that
+  has a successor and reports the rest:
+
+| was | is |
+| --- | --- |
+| `--space-2xs` to `--space-md` | `--gap-sm` between things, `--padding-sm` for an inset |
+| `--space-lg` to `--space-2xl` | `--gap` between things, `--padding` for an inset |
+| `--surface-px`, `--surface-py`; `--row-px`, `--row-py` | `--padding`; `--padding-sm` |
+| `--control-h`, `--control-h-sm` | `--control-height`, `--control-height-sm` |
+| `--size-icon`, `--size-icon-sm` | `--icon-size`, `--icon-size-sm` |
+| `--primary-10` and every other alpha step | `color-mix(in oklab, var(--primary) var(--tint), transparent)`; a line takes `--tint-strong` |
+| `--accent-50`, `--border-60`, `--muted-50` | `--accent`, `--border`, `--muted` |
+| `--control-border`, `--focus-ring-color`, `--link-color` | `--input`, `--ring`, `--link` |
+| `--shadow-xs`, `--shadow-sm`; `--shadow-md` to `--shadow-2xl`, `--popover-shadow` | `--shadow`; `--shadow-lg` |
+| `--duration-normal`, `--duration-instant`, `--ease-out` | `--duration`, `--duration-fast`, `--ease` |
+| `--leading-*`, `--weight-*`, `--tracking-*` | Text's `lineHeight`, `weight` and `caps` |
+| `--scale`, `--density-scale` | the provider's `scale` and `density` |
+| `--inverse-*` | a nested provider with `colorScheme: "dark"` |
+| `--animate-spin` and the other `--animate-*` | `--keyframes-spin` and the others, which hold the name alone: `animation: var(--keyframes-spin) 1s linear infinite` |
+
+`--text-scale` stays, and Text multiplies each step by it. A component variable you set from
+outside, such as `--content-block-p`, `--overlay-region-p`, `--field-label-width` or
+`--chart-aspect`, is the component's own now: set the theme variable it reads, or style the
+component through `className`. With Tailwind, `p-padding` and `gap-gap-sm` replace `p-md` and
+the other spacing keys, and `rounded` is the container radius.
+
+**A browser floor for `light-dark()`.** Safari 17.5 or newer; Chrome and Edge 125 and Firefox
+121 are unchanged.
+
+Run the codemod from your project over each directory that holds application code, dry
+first; the commands below show `src/`. It rewrites the moved subpaths, removes the
+stylesheet imports components now bring, renames each theme variable that has a successor,
+and reports the rest:
+
+```sh
+node node_modules/themelia-ui/scripts/consumer/codemod.mjs --dry-run src/
+node node_modules/themelia-ui/scripts/consumer/codemod.mjs src/
+```
+
+Every change with its replacement is listed in the
+migration reference (`node_modules/themelia-ui/docs/generated/migration.md`).
+
+## Upgrading to 3.0
+
+3.0 changes how the package loads, and gives a few props one shape.
+
+**Stylesheets are imported, never implied.** The package is ES modules only, and its
+JavaScript imports no CSS. Import each module's stylesheet beside its JavaScript, or
+`themelia-ui/style.css` once; a component whose stylesheet is not imported renders unstyled.
+`themelia-ui/styles` is gone: import `themelia-ui/core.css` instead. In exchange, Node loads
+the package as it is. Server rendering and test runners need no configuration for it, so
+`ssr.noExternal` and `test.server.deps.inline` entries added for the kit can go, and
+CommonJS code on Node 20.19 or later can `require()` it. Jest still needs the package
+exempted in `transformIgnorePatterns`.
+
+From 3.1, components bring their own CSS again, and server rendering with Vite lists the
+package in `ssr.noExternal`; see [Upgrading to 3.1](#upgrading-to-31).
+
+TypeScript flags the rest:
+
+- `Scope` takes `render` instead of `as`: `<Scope vars={vars} render={<section />}>`.
+- `Badge`, `Alert`, `Item`, `ItemMedia`, `InputGroupAddon` and `InputGroupButton` no longer
+  accept `null` for a variant prop; leave the prop out for the default.
+- Every `renderLink` is a `LinkRenderer`: it receives `LinkRenderProps` and returns one
+  element. `ActionLinkRenderer`, `ActionLinkRenderProps` and `ResourceCellLinkProps` are
+  gone. `Pagination` builds its addresses with `pageHref={(page) => …}`, and its
+  `renderLink` receives the href already built.
+
+A tool that reads the published catalogue (`docs/generated/component-index.json`,
+`recipes.json`, the profile records) reads `modules`, `tier` and `dependsOn` where it read
+`families`, `layer` and `dependsOnFamilies`, and passes `--module=` and `--tier=` to
+`find-component.mjs`.
+
+Run the codemod from your project, dry first. It rewrites `themelia-ui/styles`:
+
+```sh
+node node_modules/themelia-ui/scripts/consumer/codemod.mjs --dry-run src/
+node node_modules/themelia-ui/scripts/consumer/codemod.mjs src/
+```
+
+Every change with its replacement is listed in the
+migration reference (`node_modules/themelia-ui/docs/generated/migration.md`).
 
 ## Upgrading to 2.0.1
 
-A consistency release with no API change. The in-between alpha steps, per-family colour
+A consistency release with no API change. The in-between alpha steps, per-component colour
 names and glyph sizes are retired, and the codemod maps each read to the step that now owns
 its role. Every control takes `--radius-sm` at every size (checkboxes and glyph buttons
 included), badges return to it from 2.0.0's half radius, a wrapper nested in a Card steps
@@ -42,7 +212,7 @@ component name are gone, and the rest settle on fewer decisions:
 - **Two radii.** `--radius` (1rem) for containers and `--radius-sm` (0.5rem) for what sits
   inside them, both plain values. `--radius-surface`, `-popup`, `-lg` and larger read
   `--radius`; `--radius-control`, `-inner` and `-md` read `--radius-sm`. A theme that sets
-  `--radius` should set `--radius-sm` too — nothing derives it.
+  `--radius` should set `--radius-sm` too, because nothing derives it.
 - **Two text colours.** `--foreground` and `--muted-foreground`; `Text type="discrete"` is
   `type="secondary"`.
 - **One control height.** `--height-control` with `--control-h`, `-sm` and `-2xs` (34, 30 and
@@ -50,46 +220,61 @@ component name are gone, and the rest settle on fewer decisions:
   34px (were 36), menubar triggers 30px (were 28) and toast actions 24px.
 - **One density factor.** `--space-scale` is removed: `--density-scale` scales spacing and
   control geometry alike, and every density-scaled length is rounded to a whole pixel. A rule
-  that set both factors now sets `--density-scale` twice after the codemod, and the later
-  one wins.
+  that set both factors sets `--density-scale` twice after the codemod, and the later one
+  wins.
 - **One spacing ladder.** Every package spacing is a `--space-*` step (2, 4, 6, 8, 12, 16,
   24px), a control or row inset, or arithmetic over what it clears. Table cells, Item rows,
   toggles, alerts and toasts move by 2–4px.
 - **Menus stay dark by default**, now decided by the provider: `overlay.darkMenus: false`
   lets them follow the page.
 - **The typefaces ship.** `--font-sans` and `--font-mono` start with Geist and Geist Mono,
-  loaded by `core.css` from `dist/fonts/`, one file per script. The 1.x stacks named Inter and
-  JetBrains Mono and shipped neither, so text rendered in each machine's own font; anything
-  sized to its text is a little wider or narrower now. To keep your own typefaces, set both
-  tokens: the kit's files are then never downloaded. Your bundler must emit the files
-  `core.css` references, as Vite, webpack and Next.js do for `url()` in imported CSS.
+  loaded by `core.css` from `dist/fonts/`, one file per script. Text renders the same on
+  every machine now, so anything sized to its text may be a little wider or narrower. To keep
+  your own typefaces, set both tokens: the kit's files are then never downloaded. Your
+  bundler must emit the files `core.css` references, as Vite, webpack and Next.js do for
+  `url()` in imported CSS.
 - **A browser floor.** Chrome and Edge 125, Firefox 121 and Safari 16.4 or newer, set by
-  `round()`, `:has()` and `:dir()`; 1.x documented none. See
-  [installation](installation.md).
+  `round()`, `:has()` and `:dir()`. See [installation](installation.md#browser-support).
 
 Run the codemod from your project, dry first. It rewrites the moved imports, the renamed
 tokens wherever your CSS or scripts read or set them, and the renamed Tailwind utilities. It
 reports what it will not guess at: a removed token with no successor, an override that now
-sets a shared name, and `rounded-lg` and larger, which are Tailwind's own radii now:
+sets a shared name, and `rounded-md` and larger, which are Tailwind's own radii now:
 
 ```sh
 node node_modules/themelia-ui/scripts/consumer/codemod.mjs --dry-run src/
 node node_modules/themelia-ui/scripts/consumer/codemod.mjs src/
 ```
 
+The codemod does not edit component code. TypeScript flags the renamed components above and
+`type="discrete"`; a few more changes may need a line of your own:
+
+- `NavigationMenu` takes `side`, `sideOffset` and `container`, which moved from each
+  `NavigationMenuContent`.
+- `Textarea` puts `className` on the `<textarea>`; select the box with
+  `[data-slot="textarea-frame"]`.
+- `PageActions` collapses below 1024px; pass `breakpoint={1040}` to keep the old width.
+- `Comments` shows the last three replies, folds a body after six lines and shows three
+  attachments; pass `maxVisibleReplies={0}`, `clampLines={0}` or `maxVisibleAttachments={0}`
+  to show everything.
+- DatePicker's trigger is a combobox named by its label: tests find it with
+  `getByRole("combobox", { name })`.
+- `TableSkeleton` draws the table's edge; pass `framed={false}` inside a card that draws one.
+- `useCopyToClipboard` confirms for 2000ms; pass a duration to keep 1600ms.
+- A theme exported from the Theme Tweaker before 2.0 stops at the first provider; export it
+  again.
+
 Every removed name, token and utility with its replacement is listed in the
 migration reference (`node_modules/themelia-ui/docs/generated/migration.md`).
 
 ## Upgrading to 1.0.4
 
-No import migration is required. 1.0.4 refined the default shape, surface, typography and
-interaction system: structural surfaces used a 12px default radius, compact floating surfaces
-the popup radius role, Preview/Code controls an underline presentation, and nested feature
-surfaces the shared surface hierarchy.
+No import changes. 1.0.4 moved structural surfaces to a 12px default radius, compact
+floating surfaces to a shared popup radius, and nested feature surfaces to the shared
+surface hierarchy.
 
-If custom CSS overrides literal radii, menu chrome, field focus treatments, or nested
-feature surfaces, compare those overrides with the shared semantic roles before keeping
-them.
+If custom CSS overrides literal radii, menu chrome, field focus treatments or nested feature
+surfaces, compare those overrides with the shared semantic roles before keeping them.
 
 See the 1.0.4 changelog (`node_modules/themelia-ui/CHANGELOG.md`) for the complete changes.
 
@@ -101,8 +286,8 @@ TabList keeps its tablist attributes and className on the scrolling element, ins
 `tabs--rail` wrapper that also holds the scroll buttons.
 
 Review custom CSS that depends on tablist parent selectors or overrides component spacing
-and typography. Cards, content blocks, overlays, and domain blocks use the shared surface
-and typography patterns more consistently. Overlay sheets honor their configured named or
+and typography. Cards, content blocks, overlays and domain blocks use the shared surface
+and typography patterns more consistently. Overlay sheets honour their configured named or
 custom cross-axis size.
 
 See the 1.0.3 changelog (`node_modules/themelia-ui/CHANGELOG.md`) for the complete changes.
@@ -110,9 +295,9 @@ See the 1.0.3 changelog (`node_modules/themelia-ui/CHANGELOG.md`) for the comple
 ## Upgrading to 1.0.2
 
 - **Rich text, comments, and activities:** TipTap is the default editor engine. Install
-  `@tiptap/core`, `@tiptap/pm`, and `@tiptap/starter-kit` when importing those families.
+  `@tiptap/core`, `@tiptap/pm`, and `@tiptap/starter-kit` when importing those modules.
   HTML is normalized to the editor schema; use the documented custom extensions or engine
-  seam for other content. Unrelated families and root imports remain independent of these peers.
+  seam for other content. Unrelated modules and root imports remain independent of these peers.
 - **Complete translation maps:** add `applying`, `savedViews`, and `customView` to complete
   `FilterStrings` maps; add `refreshing`, `error`, `refreshError`, and `retry` to complete
   `ActivitiesStrings` maps. Partial overrides keep working. Spreading the corresponding
@@ -127,7 +312,7 @@ See the 1.0.3 changelog (`node_modules/themelia-ui/CHANGELOG.md`) for the comple
 - **Mobile filters:** below 768px, FilterLayout keeps search inline and places editors in
   an inset sheet; saved views become a select. Set `mobilePresentation="inline"` to own the
   mobile arrangement, or `filtering.mobilePresentation` when using DataView.
-- **Media Library:** `view="table"` now shows metadata columns. Use `view="list"` to retain
+- **Media Library:** `view="table"` shows metadata columns. Use `view="list"` to retain
   compact rows. Supply `onUpload` to enable the upload tab; use the upload helpers' stable
   file IDs for progress updates and `applyItemPatch` for custom record shapes.
 - **Mention completion:** custom `MentionInlineSuggestions` compositions should connect
@@ -138,40 +323,36 @@ See the 1.0.3 changelog (`node_modules/themelia-ui/CHANGELOG.md`) for the comple
   retain the normal typography. Nested providers can opt out.
 
 The changelog (`node_modules/themelia-ui/CHANGELOG.md`) records the full changes. Check the
-generated family reference for each adopted feature before adapting custom compositions.
-
-## Before 1.0
+generated module reference for each adopted feature before adapting custom compositions.
 
-A breaking change before the stable release arrived with a codemod or mechanical migration
-instructions: a consumer could apply it by search and replace or by running a script, not
-by re-reading their code and deciding.
+## How changes are classified
 
-Every change is classified as one of:
+Every change is one of:
 
-- **additive** — a new export, a new optional prop
-- **documentation-only** — no runtime or type change
-- **behaviour-preserving internal** — a refactor whose observable behaviour is identical
-- **deprecation** — the old name still works, and says what replaces it
-- **breaking** — anything else
+- **additive**: a new export, a new optional prop
+- **documentation-only**: no runtime or type change
+- **behaviour-preserving internal**: a refactor whose observable behaviour is identical
+- **deprecation**: an old name still works while a replacement is available
+- **breaking**: anything else
 
-## Within a stable major
+## Upgrade policy
 
-An alias introduced during a stable major is deprecated in that major, documented with its
-replacement, and removed only in the next one. It stays for one full stable major unless
-security or correctness makes keeping it unsafe.
+3.1 removes obsolete aliases and adapters without retaining them for another release. Pin the
+installed version until the application is ready to apply the migration guide, type-check and
+build. Breaking changes are recorded before the API snapshot is updated.
 
 ## Import paths
 
-Layer barrels — `themelia-ui/base` and its siblings — are not public and will not become
-public: one specifier pulling an entire layer would also pull every optional peer inside it.
+Tier barrels such as `themelia-ui/base` are not public and will not become public: one
+specifier pulling an entire tier would also pull every optional peer inside it.
 
 If you are migrating from a broad import, the mapping from old specifier to exact subpath is
 in `docs/generated/migration-broad-imports.md` (`node_modules/themelia-ui/docs/generated/migration-broad-imports.md`).
 
 ## What is not a compatibility surface
 
-- **Component tokens.** Component-level custom properties are plumbing and may be renamed
-  or removed in any release. The global contract listed in
+- **Component tokens.** Component-level custom properties are implementation detail and may
+  be renamed or removed in any release. The global contract listed in
   `src/styles/TOKENS.md` (`node_modules/themelia-ui/src/styles/TOKENS.md`) is the contract.
 - **CSS class names.** CSS Modules hashes them. The stable DOM hooks are the
   `{kebab-name}--component` classes and the `data-slot` attributes.
@@ -180,7 +361,6 @@ in `docs/generated/migration-broad-imports.md` (`node_modules/themelia-ui/docs/g
 
 After changing versions, type-check and build the consuming application against the installed
 package rather than a source alias. Run its unit, interaction, accessibility, and production
-bundle checks, then exercise the adopted families across the app's themes and density modes.
-You do not need this repository's scripts or source tree.
+bundle checks, then exercise the adopted modules across the app's themes and density modes.
 
 The focused matrix is in [Verifying a consuming application](verification.md).

package/.agents/skills/themelia-ui/references/provider-and-scoping.md

@@ -47,7 +47,7 @@ When an application embeds another:
 </UIScope>
 ```
 
-Its `config` is its **own overrides only**; inherited values already cascade in.
+Its `config` holds its **own overrides only**; the rest comes from the enclosing provider.
 
 `transparent` (default `true`) removes the element from layout with `display: contents`.
 Custom properties still inherit through it, because inheritance does not depend on the box.
@@ -60,31 +60,36 @@ below a slice as well as at it:
 ```tsx fragment — shape only, not a program
 <UIProvider config={{ theme: { colors: { primary: "blue", secondary: "green" } } }}>
   <UIScope config={{ theme: { colors: { primary: "red" } } }}>
-    {/* primary is red, secondary is still green */}
+    {/* useUIConfig().theme.colors: primary "red", secondary "green" */}
   </UIScope>
 </UIProvider>
 ```
 
-This applies to every record-shaped field: `theme.colors`, `theme.palette`, `theme.vars`,
-`typography.fonts`, `typography.sizes` and `motion.durations`. Below them a record is a flat
-map of token to value, and a value is replaced, not merged.
+This applies to every record-shaped field: `theme.colors`, `theme.vars`, `typography.fonts`,
+`typography.sizes` and `motion.durations`. Below them a record is a flat map of variable to
+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
+[Theming](theming.md#setting-a-theme).
 
 ## Scope — tokens only
 
-Overriding a factor requires a **scope boundary**, not just any element:
+`Scope` sets theme variables on a region, without the config machinery:
 
 ```tsx fragment — shape only, not a program
-<Scope vars={{ "--density-scale": 0.8 }}>
+<Scope vars={{ "--control-height": "2.5rem" }}>
   <Toolbar />
 </Scope>
 ```
 
-Derived tokens are declared at `:root, [data-ui-scope], [data-density], [data-theme], .light,
-.dark` (see `src/styles/SCOPES.md` (`node_modules/themelia-ui/src/styles/SCOPES.md`)). A plain
-`<div style={{ "--density-scale": 0.8 }}>` sets the variable and nothing reads it: the
-measurements above it already resolved against the old value. `Scope` renders
-`data-ui-scope`, which puts the element on that list and makes every derived token
-re-compute.
+`Scope` renders a `div` without layout. `render` picks another element, as on every
+component (`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
 
@@ -113,7 +118,8 @@ Wrap the region in `UIPortalHost` and the popups render inside it instead:
 
 The host renders one `display: contents` element inside the scope, and every portal in the
 subtree targets it, so the popup inherits from the scope. DropdownMenu, ContextMenu, Select,
-Tooltip, HoverCard, Popover, NavigationMenu and Toaster all resolve it.
+Combobox, Tooltip, HoverCard, Popover, NavigationMenu and Toaster all resolve it. An
+`Overlay` needs no host: it renders in place, and the popups inside it portal into it.
 
 Precedence, most specific first:
 
@@ -163,7 +169,7 @@ 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 replace the normal `core.css`, family CSS, or `style.css` import.
+consuming app. It does not change how the kit's CSS loads.
 
 ## Reading the config
 
@@ -180,7 +186,7 @@ provider, so read `useDefaults` rather than hard-coding a size or variant.
 `useMoneyConfig`, `useDatesConfig`, `useOverlayConfig`, `useDensity`, `useScale`,
 `useFormatting`, `useTypographyConfig`. `useDefaults` takes the component's *own* defaults
 and merges the scope's over them, which keeps the values beside the component, makes the
-call order-independent, and lets an unused family tree-shake away.
+call order-independent, and lets an unused module tree-shake away.
 
 The provider holds stable display policy: money, dates, size, density, scale. Per-feature
 policy, query timing, domain accessors, data and callbacks stay props.
@@ -195,8 +201,8 @@ still take precedence over provider defaults.
 and supplies that state to its provider. Its internal editor state alone does not change
 an enclosing provider. Keep unfinished text edits separate from applied configuration:
 for example, validate a locale with `Intl.getCanonicalLocales` before passing it to
-formatting components. The [Theme Tweaker recipe](components/features--theme-tweaker.md)
-shows this wiring and keeps the last valid preview while a locale is being typed.
+formatting components. [Editing a theme at runtime](theming.md#editing-a-theme-at-runtime)
+shows the wiring.
 
 ## Optional iPhone input zoom prevention