themelia-ui 2.0.0 → 3.0.0

package/docs/learn/api-compatibility.md

@@ -19,19 +19,19 @@ A deprecated API introduced during a stable major remains available for that maj
 named replacement and migration instructions. It is removed only in the next major unless
 security or correctness makes retaining it unsafe.
 
-Every exported declaration is snapshotted, and a removal, a newly required member or an
-incompatible type change cannot ship without a migration record. ESM, CommonJS,
-declarations, CSS exports and exact subpaths are checked against the packed tarball.
+A removal, a newly required member or an incompatible type change ships with a migration
+record: the [migration reference](../generated/migration.md) names each one with its
+replacement.
 
 ## What consumers should depend on
 
 Prefer the ready-made component, documented parts and hooks, the global theme contract,
 `data-slot`, BEM hooks, and the state attributes the primitives set (`data-open`,
 `data-checked`, `data-disabled`, `data-highlighted`, `data-popup-open`). Use `data-state`
-only where a family reference documents it; few families set it. Do not depend on source
+only where a module reference documents it; few modules set it. Do not depend on source
 paths, internal aliases, hashed CSS Module classes, undocumented DOM nesting, or
 component-owned custom properties.
 
-The generated [family references](../generated/components/INDEX.md) are the exact API
-inventory for the package version you installed. `CHANGELOG.md` records migrations and
-behavioural changes between versions.
+The generated [module references](../generated/components/INDEX.md) are the exact API
+inventory for the package version you installed. The [changelog](../../CHANGELOG.md) records
+migrations and behavioural changes between versions.

package/docs/learn/composition.md

@@ -1,23 +1,24 @@
 # Composition model
 
 The kit is designed to build product-specific UI without copying library internals. Start
-at the highest layer that already owns the interaction, then compose downward only when the
+at the highest tier that already owns the interaction, then compose downward only when the
 ready-made surface does not express the job.
 
-## The layers
+## The tiers
 
-| layer | owns | consumer use |
+| tier | owns | consumer use |
 | --- | --- | --- |
-| typography | text roles | keep type, colour, truncation, and semantics consistent |
-| primitives | one formatted value | render money, dates, people, files, and other values |
-| base | one generic UI concept | controls, overlays, rows, cards, feedback, and structure |
-| layout | page and application shells | arrange routes without owning routing or data |
-| features | an interaction lifecycle | use controlled state, callbacks, accessors, parts, or hooks |
-| patterns | a subject-shaped arrangement | assemble base, layout, and feature families |
-| admin | terminal admin presentation | build on general families without leaking admin vocabulary down |
-
-`layout` and `features` are siblings. A pattern may compose both; neither may import a
-pattern. The complete generated graph is in [Profiles](../generated/profiles.md).
+| Primitives | one formatted value | render money, dates, people, files, and other values |
+| Base | one generic UI concept | controls, overlays, rows, cards, feedback, and structure |
+| Base | text roles, in `base/typography` | keep type, colour, truncation, and semantics consistent |
+| Layout | page and application shells | arrange routes without owning routing or data |
+| Features | an interaction lifecycle | use controlled state, callbacks, accessors, parts, or hooks |
+| Blocks | a subject-shaped arrangement | assemble base, layout, and feature modules |
+| Blocks | terminal admin presentation, in the admin blocks | build on general modules without leaking admin vocabulary down |
+
+`base/typography` sits below Primitives. Layout and Features are siblings. A block may
+compose both; neither may import a block. The complete generated graph is in
+[Profiles](../generated/profiles.md).
 
 ## The composition ladder
 
@@ -30,12 +31,12 @@ Use the lowest rung that solves the real requirement:
 5. Render props when a region needs the component's live state.
 6. Exported parts for assembling a different surface.
 7. A headless hook when the package presentation cannot express the design.
-8. A documented recipe that wires several families into a screen-level result.
+8. A documented recipe that wires several modules into a screen-level result.
 
-Not every family needs every rung. A passive Badge does not need controlled state; a feature
+Not every module needs every rung. A passive Badge does not need controlled state; a feature
 with an interaction lifecycle normally offers several. The generated
-[composition audit](../generated/composition-ladder.md) lists which seams each feature
-family exposes.
+[composition ladder](../generated/composition-ladder.md) lists which seams each feature
+module exposes.
 
 ## Build a business component
 
@@ -105,7 +106,7 @@ responsive geometry, tokens, and reusable interaction contracts.
 ## Common application compositions
 
 These are boundaries, not new package abstractions. Adapt the application-owned data and
-callbacks, then open each linked family reference for the complete prop contract.
+callbacks, then open each linked module reference for the complete prop contract.
 
 ### Dashboard
 
@@ -120,7 +121,7 @@ import "themelia-ui/layout/page.css"
 </Page>
 ```
 
-The pattern owns metric presentation and responsive columns. The app owns the query, time
+The block owns metric presentation and responsive columns. The app owns the query, time
 window, permission-filtered figures, and what clicking a metric means.
 
 ### Resource index
@@ -261,7 +262,7 @@ export function RenameRecord({ initialName, save }: {
 
 ### Responsive resource filters
 
-Install the optional peers listed in the DataView family reference. The ready surface shares
+Install the optional peers listed in the DataView module reference. The ready surface shares
 one filter state across the desktop bar and mobile sheet; the application supplies records
 and owns fetching. This example filters local rows. For server filtering, wire the public
 filtering contract to your query layer instead of filtering an already paged subset twice.
@@ -317,22 +318,22 @@ export function SettingsTabs() {
 
 | Situation | Composition rule |
 | --- | --- |
-| Initial loading | Use the family's loading contract where available; do not show a false empty result. |
+| Initial loading | Use the module's loading contract where available; do not show a false empty result. |
 | Refresh | Keep existing data and drafts visible where supported; distinguish refresh from first load. |
 | Empty or no matches | Distinguish an empty collection from filters excluding every result; offer the relevant next action. |
 | Error | Preserve user input, show recoverable feedback, and wire retry to the app's data operation. |
 | Pending mutation | Prevent duplicate actions; keep progress and errors associated with the initiating control. |
-| Narrow viewport | Use the family's mobile presentation (such as the filter sheet); keep state shared with desktop. |
+| Narrow viewport | Use the module's mobile presentation (such as the filter sheet); keep state shared with desktop. |
 | Typography/theme override | Let semantic owners inherit provider defaults; verify density changes spacing without demoting body copy. |
 
-Only use states the selected family exposes; the API reference is authoritative. The
+Only use states the selected module exposes; the API reference is authoritative. The
 complete examples above type-check against the built package, but their application
 callbacks are illustrative: verify persistence and browser behaviour in your app.
 
 ## When to wrap, compose, or contribute
 
-- **Wrap** when the product needs a stable local name or defaults around one family.
-- **Compose** when several public families form a product concept.
+- **Wrap** when the product needs a stable local name or defaults around one module.
+- **Compose** when several public modules form a product concept.
 - **Use parts or a hook** when a ready-made feature has the right lifecycle but the wrong
   presentation.
 - **Contribute to the package** only when the missing concept is domain-neutral, repeats in
@@ -341,5 +342,5 @@ callbacks are illustrative: verify persistence and browser behaviour in your app
   are not compatibility surfaces. Public props, exported parts, hooks, `data-slot`, BEM
   hooks, and global theme tokens are.
 
-Open [the family API index](../generated/components/INDEX.md) after choosing a family. It
-contains every public declaration and the live recipes attributed to that family.
+Open [the module API index](../generated/components/INDEX.md) after choosing a module. It
+contains every public declaration and the live recipes attributed to that module.

package/docs/learn/forms.md

@@ -86,5 +86,9 @@ When the fields come from a schema at runtime, use `features/schema-form`. When
 known at build time, write them: a schema adds indirection that only pays off when the shape
 is genuinely dynamic.
 
-Preview routes with recipes: `/form-binding`, `/form-field`, `/form-workflow`, `/schema-form`
-(search them with the finder's `--route=` option).
+The preview recipes for these patterns are on the routes `/form-binding`, `/form-field`,
+`/form-workflow` and `/schema-form`. The finder lists the modules behind one:
+
+```bash
+node node_modules/themelia-ui/scripts/consumer/find-component.mjs --route=/form-field
+```

package/docs/learn/framework-wiring.md

@@ -6,21 +6,35 @@ runtime. Those concerns meet through explicit props rather than hidden framework
 
 ## Routing
 
-Pass the router's link through `render` or a family's documented `renderLink` adapter. Do
-not put navigation in an `onClick` when the destination is a URL: a real link preserves
-open-in-new-tab, the status-bar destination, and browser semantics.
+Pass the router's link through `render`, or through `renderLink` where a component renders
+links of its own. Do not put navigation in an `onClick` when the destination is a URL: a
+real link preserves open-in-new-tab, the status-bar destination, and browser semantics.
 
 ```tsx fragment — replace AppLink with the link component from the consuming router
 <Button render={<AppLink to="/invoices/new" />}>New invoice</Button>
 ```
 
-Layout navigation adapters accept the same idea at the page or shell boundary. The kit does
-not import React Router, Next.js, Remix, or another router.
+Every `renderLink` takes the same function, a `LinkRenderer`: the sidebar and header, page
+headers and actions, menus and action buttons, navigation tabs, pagination, and table
+cells. Write it once:
+
+```tsx fragment — replace AppLink with the link component from the consuming router
+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>
+```
+
+Return one element and spread the rest of the props onto it: they carry the class, the
+`aria-current` of the current page and the click handler the component needs. `active`,
+`disabled` and `external` are hints to read. `Pagination` builds its addresses with
+`pageHref={(page) => ...}` and then renders them through the same `renderLink`. The kit
+does not import React Router, Next.js, Remix, or another router.
 
 ## Queries and mutations
 
 Fetch records outside the component, pass data and loading/error state in, and connect
-mutations through callbacks. A callback may return a promise when the family documents an
+mutations through callbacks. A callback may return a promise when the module documents an
 async lifecycle; the application decides cache invalidation, retries, and error reporting.
 
 ```tsx fragment — query client and mutation implementation belong to the application
@@ -40,7 +54,7 @@ async lifecycle; the application decides cache invalidation, retries, and error
 
 Resolve authorization before constructing actions. Omit an action the user cannot perform;
 disable it only when seeing the unavailable action is itself useful and provide the reason
-through the family's tooltip or description seam.
+through the module's tooltip or description seam.
 
 ## Translation
 
@@ -50,7 +64,7 @@ from the complete shape rather than guessing keys; see [Internationalization](./
 
 ## Server rendering and client boundaries
 
-Import server-pure formatting families freely. Interactive families carry their own
+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.
@@ -61,11 +75,12 @@ application adapter unless the documented public hooks are insufficient.
 
 ## Vite, Next.js, and CSS entrypoints
 
-Vite and similar bundlers can keep each exact `.css` import beside the component-family
-import. In a framework that restricts where global CSS may be imported, collect those same
-exact family stylesheets in its permitted application or route-layout entry. Do not replace
-them with source paths, and do not import `style.css` merely to avoid learning which families
-the route uses.
+The JavaScript imports no CSS: import the exact module stylesheet beside the component. In a
+framework that restricts where global CSS may be imported, collect the same module
+stylesheets in its permitted application or route-layout entry. Do not replace them with
+source paths. `style.css` loads every module; prefer module stylesheets when a route uses a
+few. Server rendering and test runners are covered in
+[Loading the CSS](./installation.md#loading-the-css).
 
 Server-rendered HTML and the client bundle must load the same theme tokens before hydration.
 Apply the theme attribute and provider configuration from the same persisted value to avoid

package/docs/learn/i18n.md

@@ -5,8 +5,8 @@ overridable, and nothing in it inspects `navigator.language` or imports a transl
 
 ## Strings
 
-Each family exports a `*Strings` interface and a `default*Strings` object, and takes a
-`strings` prop:
+Each module exports a `*Strings` interface and a `default*Strings` object, and its
+components take a `strings` prop:
 
 ```tsx fragment — shape only, not a program
 <Copyable strings={{ copy: "Kopieren", copied: "Kopiert" }} value={apiKey} />
@@ -19,7 +19,7 @@ partially, and every sibling key keeps its default:
 <DataTable strings={{ pagination: { previous: "Zurück", next: "Weiter" } }} />
 ```
 
-Where a family types its prop as `Partial<…Strings>`, TypeScript still asks for each nested
+Where a module types its prop as `Partial<…Strings>`, TypeScript still asks for each nested
 group whole; spread the group's default, for example
 `kind: { ...defaultTransactionStrings.kind, refund: "Rückerstattung" }`.
 
@@ -40,7 +40,7 @@ two forms. Replace the whole function, not the words inside it.
 
 ### What consumers can rely on
 
-- Component-owned visible and accessible copy belongs to the family's typed `strings`
+- Component-owned visible and accessible copy belongs to the module's typed `strings`
   contract, including placeholders, titles, alternative text, and announcements.
 - Product/domain copy still arrives through application data, children, or documented props;
   the package does not translate it or decide which message catalogue to use.

package/docs/learn/installation.md

@@ -5,7 +5,7 @@ npm install themelia-ui
 ```
 
 React 19 and `react-dom` are required peers. Everything else is optional and only pulled in
-by the family that needs it — see [Optional peers](#optional-peers).
+by the module that needs it; see [Optional peers](#optional-peers).
 
 ## Browser support
 
@@ -17,8 +17,8 @@ list of right-to-left languages and ignores `dir="rtl"`.
 
 ## Import exactly what you use
 
-The package publishes one subpath per family and no broad barrels: there is no
-`themelia-ui/base`, and there will not be. A barrel would pull every family into the bundle
+The package publishes one subpath per module and no broad barrels: there is no
+`themelia-ui/base`, and there will not be. A barrel would pull every module into the bundle
 and make an optional peer reachable from an import that did not ask for it.
 
 ```tsx compile
@@ -27,46 +27,62 @@ import { Stack } from "themelia-ui/base/structure"
 import { Money } from "themelia-ui/primitives"
 ```
 
-The root `themelia-ui` export exists and is optional-peer-free, but it is for
+The root `themelia-ui` export exists and is free of optional peers, but it is for
 prototyping. Shipping code should name subpaths, which keeps the JS and CSS to what you
 use.
 
-The exact import for every family is in
+The exact import for every module is in
 [`docs/generated/imports.md`](../generated/imports.md), generated from the package manifest.
 
-## CSS
+## Loading the CSS
 
-Import each family's stylesheet beside its components. The ESM build also imports its own
-CSS, but the CJS build, SSR without a CSS loader and most test runners do not; the explicit
-import behaves the same everywhere and keeps the selected CSS visible in application source.
-Each family stylesheet imports the shared tokens, themes and cascade layer order from
-`core.css` for you.
+The package ships three kinds of stylesheet:
 
-```tsx fragment — shape only, not a program
-import "themelia-ui/base/buttons.css"
-```
+| Import | Contains |
+| --- | --- |
+| `themelia-ui/<module>.css` | `core.css`, then the rules of the module and of the modules it draws with |
+| `themelia-ui/style.css` | `core.css` and every module, in one file |
+| `themelia-ui/core.css` | Tokens, themes, typefaces, the base reset and the cascade layer order; no component rules |
+
+[`imports.md`](../generated/imports.md) gives each module's stylesheet path. A module whose
+components draw nothing has no stylesheet.
+
+### Import the stylesheets
+
+The JavaScript imports no CSS. Import each module's stylesheet beside its JavaScript, as the
+examples in these docs do, or `style.css` once. Vite, webpack, Rspack, Next.js and other
+bundlers that handle CSS imports include each file once, however many modules import it. A
+component whose stylesheet is not imported renders unstyled.
+
+### In Node
+
+The package is ES modules, and its JavaScript imports no CSS, so Node loads it as it is:
+server rendering and test runners need no configuration for it, and CommonJS code on Node
+20.19 or later can `require()` it. Jest is the exception, because it transforms nothing in
+`node_modules` by default: exempt the package in `transformIgnorePatterns`.
 
-Import `themelia-ui/core.css` on its own only when application CSS needs the token
-contract before any family stylesheet is loaded. Do not add it merely because you imported
-a family stylesheet; that sheet already imports it.
+### `core.css` on its own
 
-A family whose components draw nothing has no sheet. `imports.md` records which.
+Every module stylesheet begins by importing `core.css`, so a component never needs a
+separate core import to render correctly. Import `core.css` on its own when application CSS
+uses the tokens on a page without kit components, or to place the kit's layers next to
+another layered stylesheet, as in the [Tailwind setup](./theming.md#tailwind-css-v4).
 
-If you would rather not track sheets per family, `themelia-ui/style.css` is the
-deduplicated union of all of them, larger than any one app needs.
+### Overriding the kit
 
-Import application overrides after the kit. Component rules live in cascade layers, so
-ordinary unlayered consumer CSS wins without specificity tricks. Select with stable
-`data-slot` and BEM hooks, and select a state with the attributes the primitives set
-(`data-open`, `data-checked`, `data-disabled`, `data-highlighted`, `data-popup-open`).
+Component rules live in the cascade layers `tokens, theming, base, components, utilities`,
+so unlayered application CSS wins over them whatever its order or specificity. Select with
+the stable `data-slot` attributes and BEM hooks such as `{name}--component`, and select a
+state with the attributes the primitives set (`data-open`, `data-checked`, `data-disabled`,
+`data-highlighted`, `data-popup-open`). Hashed CSS Module class names change between
+releases.
 
 ## Optional peers
 
-Every peer other than React is optional, and each is reachable only from the families that
+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.
 
-The peer-to-family table is in [`docs/generated/imports.md`](../generated/imports.md),
-generated from and checked against the package graph.
+The peer-to-module table is in [`docs/generated/imports.md`](../generated/imports.md).
 
 The `react-hook-form` adapter, for example, lives behind its own subpath so
 `themelia-ui/forms` stays dependency-free; a consumer on plain React state never resolves
@@ -76,10 +92,10 @@ react-hook-form. See [Forms](./forms.md).
 
 The package ships two profiles from one install:
 
-- **General** — typography, formatted primitives, controls, generic patterns, layout shells
+- **General**: typography, formatted primitives, controls, generic blocks, layout shells
   and domain-neutral interaction features.
-- **Admin** — B2B and admin presentation, built only from the general profile.
+- **Admin**: B2B and admin presentation, built only from the general profile.
 
-Which families belong to which is in
-[`docs/generated/profiles.md`](../generated/profiles.md). An admin family may build on a
+Which modules belong to which is in
+[`docs/generated/profiles.md`](../generated/profiles.md). An admin module may build on a
 general one, never the reverse.

package/docs/learn/migration.md

@@ -1,6 +1,60 @@
 # Compatibility and migration
 
-The package is `2.0.0`. 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.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`.
+
+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](../generated/migration.md).
+
+## Upgrading to 2.0.1
+
+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
+down to it, every card-like surface is `--card` in dark, and the current navigation item is
+neutral. The groups are in [the token contract](../../src/styles/TOKENS.md).
+
+Run the codemod from your project, dry first, if your CSS reads a retired step:
+
+```sh
+node node_modules/themelia-ui/scripts/consumer/codemod.mjs --dry-run src/
+```
 
 ## Upgrading to 2.0
 
@@ -27,7 +81,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
@@ -35,46 +89,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](../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](../../CHANGELOG.md#104--2026-09-22) for the complete changes.
 
@@ -86,8 +155,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](../../CHANGELOG.md#103--2026-09-17) for the complete changes.
@@ -95,9 +164,9 @@ See the [1.0.3 changelog](../../CHANGELOG.md#103--2026-09-17) for the complete c
 ## 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
@@ -112,7 +181,7 @@ See the [1.0.3 changelog](../../CHANGELOG.md#103--2026-09-17) for the complete c
 - **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
@@ -123,21 +192,17 @@ See the [1.0.3 changelog](../../CHANGELOG.md#103--2026-09-17) for the complete c
   retain the normal typography. Nested providers can opt out.
 
 The [changelog](../../CHANGELOG.md#102--2026-09-16) 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**: the old name still works, and says what replaces it
+- **breaking**: anything else
 
 ## Within a stable major
 
@@ -147,16 +212,16 @@ security or correctness makes keeping it unsafe.
 
 ## 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`](../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`](../../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.
@@ -165,7 +230,6 @@ in [`docs/generated/migration-broad-imports.md`](../generated/migration-broad-im
 
 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).