themelia-ui 2.0.0 → 3.0.0

package/docs/generated/composition-ladder.md

@@ -3,18 +3,18 @@
 # The composition ladder
 
 The [composition model](../learn/composition.md) lists eight rungs, from ordinary props to a
-documentation recipe. A family offers the *smallest sufficient* seam — not all eight, and
+documentation recipe. A module offers the *smallest sufficient* seam — not all eight, and
 not a headless hook where a prop would do.
 
 The rungs are ordinary props; controlled state and callbacks when state exists; accessors;
 named slots; render props; exported parts; headless hooks; and complete recipes. Passive
-families may stop at the first rung. Interaction features normally expose several.
+modules may stop at the first rung. Interaction features normally expose several.
 
-This table is derived from what each family declares, so it cannot describe a seam that
-was removed or miss one that was added. The table focuses on feature families, where the
+This table is derived from what each module declares, so it cannot describe a seam that
+was removed or miss one that was added. The table focuses on feature modules, where the
 higher rungs are meaningful; the columns start at accessors.
 
-| family | accessors | slots | render props | headless hook | partials | recipe |
+| module | accessors | slots | render props | headless hook | partials | recipe |
 | --- | :-: | :-: | :-: | :-: | :-: | :-: |
 | `features/actions` | ● | ● | · | ● | ● | ● |
 | `features/activities` | ● | ● | ● | ● | ● | ● |
@@ -38,7 +38,7 @@ higher rungs are meaningful; the columns start at accessors.
 | `features/rich-text-editor/tiptap` | · | · | · | · | · | · |
 | `features/schema-form` | ● | · | ● | ● | ● | ● |
 | `features/sync` | · | · | · | · | · | ● |
-| `features/table` | ● | ● | ● | ● | ● | ● |
+| `features/table` | ● | ● | · | ● | ● | ● |
 | `features/theme-tweaker` | · | ● | · | ● | ● | ● |
 
 ## The four the plan names

package/docs/generated/imports.md

@@ -2,17 +2,16 @@
 
 # Exact imports
 
-Every family has one subpath. There are no layer barrels: `themelia-ui/base` and its three
-siblings were removed because one specifier pulled an entire layer and every optional peer
-inside it. The root carries the provider and the display primitives, both peer-free.
+Every module has one subpath. There are no tier barrels: `themelia-ui/base` and its three
+siblings do not exist, because one specifier would pull an entire tier and every optional
+peer inside it. The root carries the provider and the display primitives, both peer-free.
 
-Import the stylesheet column beside the exact JavaScript subpath. ESM bundlers also
-discover the family rules through the module graph, but the explicit form behaves the
-same in CJS and makes the selected CSS visible in application source.
+Import the stylesheet column beside the exact JavaScript subpath, or `style.css` once. The
+JavaScript imports no CSS, so a module without its stylesheet renders unstyled.
 
-## general profile — 95 families
+## general profile — 95 modules
 
-| family | import | stylesheet | optional peers |
+| module | import | stylesheet | optional peers |
 | --- | --- | --- | --- |
 | `base/accordion` | `themelia-ui/base/accordion` | `themelia-ui/base/accordion.css` | — |
 | `base/action-menu` | `themelia-ui/base/action-menu` | `themelia-ui/base/action-menu.css` | — |
@@ -110,17 +109,17 @@ same in CJS and makes the selected CSS visible in application source.
 | `theming` | `themelia-ui/theming` | — | — |
 | `ui-provider` | `themelia-ui/ui-provider` | — | — |
 
-## admin profile — 2 families
+## admin profile — 2 modules
 
-| family | import | stylesheet | optional peers |
+| module | import | stylesheet | optional peers |
 | --- | --- | --- | --- |
 | `admin/patterns/access` | `themelia-ui/admin/patterns/access` | `themelia-ui/admin/patterns/access.css` | — |
 | `admin/patterns/commerce` | `themelia-ui/admin/patterns/commerce` | `themelia-ui/admin/patterns/commerce.css` | — |
 
 ## Optional peers — 15 of them
 
-Each is reachable only from the families below, so a consumer who never imports one never
-resolves it. Release verification rejects a family that reaches an undeclared peer.
+Each is reachable only from the modules below, so a consumer who never imports one never
+resolves it. Release verification rejects a module that reaches an undeclared peer.
 
 | peer | reachable from |
 | --- | --- |

package/docs/generated/migration-broad-imports.json

@@ -1,5 +1,5 @@
 {
-  "note": "Generated by scripts/gen-migration-map.mjs. Phase 8 codemods read this file.",
+  "note": "Generated by scripts/gen-migration-map.mjs. The codemod reads this file.",
   "removedSubpaths": [
     "themelia-ui/base",
     "themelia-ui/features",
@@ -52,8 +52,6 @@
     "ActionIcon": "themelia-ui/base/action-menu",
     "ActionLifecycleEvent": "themelia-ui/features/actions",
     "ActionLifecycleType": "themelia-ui/features/actions",
-    "ActionLinkRenderer": "themelia-ui/base/action-menu",
-    "ActionLinkRenderProps": "themelia-ui/base/action-menu",
     "ActionMenu": "themelia-ui/base/action-menu",
     "ActionMenuLabelVisibility": "themelia-ui/base/action-menu",
     "ActionMenuProps": "themelia-ui/base/action-menu",
@@ -1114,6 +1112,8 @@
     "LanguageSwitcherVariant": "themelia-ui/base/navigation",
     "LeafletDrawModule": "themelia-ui/features/map",
     "LeafletModule": "themelia-ui/features/map",
+    "LinkRenderer": "themelia-ui/base/action-menu",
+    "LinkRenderProps": "themelia-ui/base/action-menu",
     "ListRadioGroup": "themelia-ui/base/choice-inputs",
     "ListRadioGroupProps": "themelia-ui/base/choice-inputs",
     "ListRadioOption": "themelia-ui/base/choice-inputs",
@@ -1613,7 +1613,6 @@
     "ResourceBlockSurface": "themelia-ui/features/resource",
     "ResourceCell": "themelia-ui/features/table",
     "ResourceCellBadge": "themelia-ui/features/table",
-    "ResourceCellLinkProps": "themelia-ui/features/table",
     "ResourceCellMetadataItem": "themelia-ui/features/table",
     "ResourceCellProps": "themelia-ui/features/table",
     "ResourceCombobox": "themelia-ui/features/combobox",
@@ -2156,6 +2155,32 @@
     "zodValidator": "themelia-ui/features/filters"
   },
   "ambiguous": {
+    "LinkRenderer": [
+      "./base/action-menu",
+      "./base/cards",
+      "./base/navigation",
+      "./features/table",
+      "./layout/auth",
+      "./layout/header",
+      "./layout/navigation",
+      "./layout/page",
+      "./layout/settings",
+      "./layout/sidebar",
+      "./layout/workspace"
+    ],
+    "LinkRenderProps": [
+      "./base/action-menu",
+      "./base/cards",
+      "./base/navigation",
+      "./features/table",
+      "./layout/auth",
+      "./layout/header",
+      "./layout/navigation",
+      "./layout/page",
+      "./layout/settings",
+      "./layout/sidebar",
+      "./layout/workspace"
+    ],
     "ActionDefinition": [
       "./base/action-menu",
       "./features/actions"

package/docs/generated/migration-broad-imports.md

@@ -15,8 +15,8 @@ every component:
 + import { Button } from "themelia-ui/base/buttons"
 ```
 
-A broad barrel let one specifier pull an entire layer, and with it every optional peer
-inside that layer. Importing a button resolved recharts, leaflet and dnd-kit. The root is
+A broad barrel let one specifier pull an entire tier, and with it every optional peer
+inside that tier. Importing a button resolved recharts, leaflet and dnd-kit. The root is
 now the provider and the display primitives, both peer-free; everything else has an exact
 subpath.
 
@@ -35,7 +35,7 @@ own worse stepper instead.
 | `themelia-ui/blocks/commerce` | `themelia-ui/admin/patterns/commerce` |
 | `themelia-ui/blocks/admin` | `themelia-ui/admin/patterns/access` |
 
-## Where each symbol went (2136)
+## Where each symbol went (2135)
 
 | symbol | import from |
 | --- | --- |
@@ -73,8 +73,6 @@ own worse stepper instead.
 | `ActionIcon` | `themelia-ui/base/action-menu` |
 | `ActionLifecycleEvent` | `themelia-ui/features/actions` |
 | `ActionLifecycleType` | `themelia-ui/features/actions` |
-| `ActionLinkRenderer` | `themelia-ui/base/action-menu` |
-| `ActionLinkRenderProps` | `themelia-ui/base/action-menu` |
 | `ActionMenu` | `themelia-ui/base/action-menu` |
 | `ActionMenuLabelVisibility` | `themelia-ui/base/action-menu` |
 | `ActionMenuProps` | `themelia-ui/base/action-menu` |
@@ -1135,6 +1133,8 @@ own worse stepper instead.
 | `LanguageSwitcherVariant` | `themelia-ui/base/navigation` |
 | `LeafletDrawModule` | `themelia-ui/features/map` |
 | `LeafletModule` | `themelia-ui/features/map` |
+| `LinkRenderer` | `themelia-ui/base/action-menu` |
+| `LinkRenderProps` | `themelia-ui/base/action-menu` |
 | `ListRadioGroup` | `themelia-ui/base/choice-inputs` |
 | `ListRadioGroupProps` | `themelia-ui/base/choice-inputs` |
 | `ListRadioOption` | `themelia-ui/base/choice-inputs` |
@@ -1634,7 +1634,6 @@ own worse stepper instead.
 | `ResourceBlockSurface` | `themelia-ui/features/resource` |
 | `ResourceCell` | `themelia-ui/features/table` |
 | `ResourceCellBadge` | `themelia-ui/features/table` |
-| `ResourceCellLinkProps` | `themelia-ui/features/table` |
 | `ResourceCellMetadataItem` | `themelia-ui/features/table` |
 | `ResourceCellProps` | `themelia-ui/features/table` |
 | `ResourceCombobox` | `themelia-ui/features/combobox` |
@@ -2178,9 +2177,11 @@ own worse stepper instead.
 
 ## Ambiguous names
 
-These are exported by more than one family. The subpath decides which one you get, and
-the broad barrel used to decide for you — silently, by layer order.
+These are exported by more than one module. The subpath decides which one you get, and
+the broad barrel used to decide for you — silently, by tier order.
 
+- `LinkRenderer` — `themelia-ui/base/action-menu`, `themelia-ui/base/cards`, `themelia-ui/base/navigation`, `themelia-ui/features/table`, `themelia-ui/layout/auth`, `themelia-ui/layout/header`, `themelia-ui/layout/navigation`, `themelia-ui/layout/page`, `themelia-ui/layout/settings`, `themelia-ui/layout/sidebar`, `themelia-ui/layout/workspace`
+- `LinkRenderProps` — `themelia-ui/base/action-menu`, `themelia-ui/base/cards`, `themelia-ui/base/navigation`, `themelia-ui/features/table`, `themelia-ui/layout/auth`, `themelia-ui/layout/header`, `themelia-ui/layout/navigation`, `themelia-ui/layout/page`, `themelia-ui/layout/settings`, `themelia-ui/layout/sidebar`, `themelia-ui/layout/workspace`
 - `ActionDefinition` — `themelia-ui/base/action-menu`, `themelia-ui/features/actions`
 - `ActionPlacement` — `themelia-ui/base/action-menu`, `themelia-ui/features/actions`
 - `ActionPredicate` — `themelia-ui/base/action-menu`, `themelia-ui/features/actions`

package/docs/generated/migration-codemod.json

@@ -7,7 +7,8 @@
     "themelia-ui/blocks/access": "themelia-ui/admin/patterns/access",
     "themelia-ui/blocks/commerce": "themelia-ui/admin/patterns/commerce",
     "@/services/actions": "themelia-ui/features/actions",
-    "themelia-ui/features/suggestions": "themelia-ui/features/combobox"
+    "themelia-ui/features/suggestions": "themelia-ui/features/combobox",
+    "themelia-ui/styles": "themelia-ui/core.css"
   },
   "tokens": {
     "--radius-surface": "--radius",
@@ -47,8 +48,8 @@
     "--switch-track-h": "--choice-size",
     "--menu-shadow": "--popover-shadow",
     "--menu-ring-width": "--border-width",
-    "--sidebar-group-action-size": "--sidebar-action-size",
-    "--sidebar-menu-action-size": "--sidebar-action-size",
+    "--sidebar-group-action-size": "--size-icon-lg",
+    "--sidebar-menu-action-size": "--size-icon-lg",
     "--button-px": "--control-px",
     "--button-px-icon": "--control-px-sm",
     "--button-gap": "--space-sm",
@@ -78,7 +79,32 @@
     "--calendar-months-gap": "--space-xl",
     "--skeleton-block-gap": "--space-xl",
     "--space-scale": "--density-scale",
-    "--density-preset-scale": "--density-scale"
+    "--density-preset-scale": "--density-scale",
+    "--card-framed-bg": "--card",
+    "--alert-description-fg": "--text-role-secondary",
+    "--alert-link-hover": "--text-role-main",
+    "--alert-meta-label-fg": "--text-role-secondary",
+    "--mention-destructive-fg": "--destructive-accent",
+    "--menu-item-destructive-bg-hover": "--destructive-10",
+    "--segmented-chip-bg": "--popover",
+    "--aside-nav-item-h": "--control-h-sm",
+    "--avatar-group-ring-width": "--border-width-strong",
+    "--item-title-underline-offset": "--link-underline-offset",
+    "--product-thumb-size": "--size-medallion",
+    "--stepper-line": "--border-width-strong",
+    "--timeline-dot-icon": "--size-icon-sm",
+    "--tooltip-arrow-radius": null,
+    "--primary-12": "--primary-10",
+    "--success-15": "--success-10",
+    "--info-15": "--info-10",
+    "--info-40": "--info-30",
+    "--warning-50": "--warning-10",
+    "--muted-30": "--muted-50",
+    "--muted-35": "--muted-20",
+    "--border-50": "--border-60",
+    "--border-70": "--border",
+    "--sidebar-action-size": "--size-icon-lg",
+    "--picker-clear-size": "--size-icon"
   },
   "classes": {
     "rounded-surface": "rounded-(--radius)",

package/docs/generated/migration.md

@@ -19,13 +19,13 @@ worse than no codemod.
 
 ## Moved subpaths
 
-The layer above features was renamed, and the admin domains moved into the admin profile. Every one of these is a pure specifier rewrite, which is why the codemod does them for you — the stylesheet import moves with its family.
+The tier above Features moved from `blocks/` to `patterns/`, and the admin domains moved into the admin profile. Every one of these is a pure specifier rewrite, which is why the codemod does them for you — the stylesheet import moves with its module.
 
 ### `themelia-ui/blocks/analytics`
 
 **Becomes** `themelia-ui/patterns/analytics` — mechanical, the codemod does it.
 
-`blocks/` became `patterns/`, and the admin domains moved under `admin/patterns/`. The layer kept its position above features; only the name changed.
+`blocks/` became `patterns/`, and the admin domains moved under `admin/patterns/`. The tier kept its position above Features; only the subpath changed.
 
 ### `themelia-ui/blocks/onboarding`
 
@@ -43,7 +43,7 @@ See above.
 
 **Becomes** `themelia-ui/admin/patterns/access` — mechanical, the codemod does it.
 
-Admin domains moved into the admin profile, which may build on general families but never the reverse.
+Admin domains moved into the admin profile, which may build on general modules but never the reverse.
 
 ### `themelia-ui/blocks/commerce`
 
@@ -55,7 +55,7 @@ See above.
 
 **Becomes** `themelia-ui/features/actions` — mechanical, the codemod does it.
 
-The action registry was never published; it lived at a source alias no consumer could resolve. It is a family now.
+The action registry was never published; it lived at a source alias no consumer could resolve. It is a module now.
 
 ### `themelia-ui/features/suggestions`
 
@@ -63,6 +63,12 @@ The action registry was never published; it lived at a source alias no consumer
 
 The entry point only re-exported SuggestionsCombobox, useSuggestions, defaultSuggestionsStrings and their types (MaybePromise, SuggestionsComboboxProps, SuggestionsErrorContext, SuggestionsFetchContext, SuggestionsStrings, UseSuggestionsConfig, UseSuggestionsResult) from features/combobox, where they live. Every name is published there unchanged, so this is a pure specifier rewrite; themelia-ui/features/suggestions.css goes too, and themelia-ui/features/combobox.css styles the picker.
 
+### `themelia-ui/styles`
+
+**Becomes** `themelia-ui/core.css` — mechanical, the codemod does it.
+
+The JavaScript imports no CSS, so the entry that only imported the core stylesheet is gone; import the stylesheet itself.
+
 ## Provider changes
 
 Behaviour, not names. `UIProvider` still exists and still behaves as it did; what changed is that the pieces it composes are now separately available, and that reaching outside the React tree is opt-in.
@@ -113,15 +119,15 @@ One idea had two spellings. `render` takes the element as a value, so it can be
 
 ### `contentAs`
 
-**Becomes** `contentRender` — mechanical, the codemod does it.
+**Becomes** `contentRender` — a direct rename, by hand.
 
-One idea in two vocabularies. Every other polymorphic seam in the kit is `render`, and this one shipped as `contentAs` — a string union naming an element rather than an element to render. `verify api-vocabulary` exists to catch exactly this and its regex only matched `as?: ElementType`, so the single instance of the drift outlived the rule against it.
+One idea in two vocabularies. Every other polymorphic seam in the kit is `render`, and this one shipped as `contentAs` — a string union naming an element rather than an element to render.
 
 `contentAs="div"` becomes `contentRender={<div />}`. Mechanical: the value goes from an element NAME to an element, so `"section"` becomes `<section />`.
 
 ### `FormFieldProps htmlFor: string`
 
-**Becomes** `FormFieldProps htmlFor: string | false` — mechanical, the codemod does it.
+**Becomes** `FormFieldProps htmlFor: string | false` — a direct rename, by hand.
 
 `false` is how a caller says the field wraps a GROUP of controls rather than one — a radio set, a segmented control, a pair of date inputs. There is no single element for a label to point at, so `FormField` stops inventing an id and describes the group instead. Widening an optional input prop: every call site passing a string, and every call site omitting it, is unaffected.
 
@@ -137,7 +143,7 @@ Delete the override. The copy it appeared to control is either supplied by you a
 
 ### `HeaderNotificationsStrings without unreadItem`
 
-**Becomes** `HeaderNotificationsStrings.unreadItem` — mechanical, the codemod does it.
+**Becomes** `HeaderNotificationsStrings.unreadItem` — a direct rename, by hand.
 
 Unread was drawn as a tint and a dot, and neither reaches a screen reader — colour alone is not a state — so the row also carried the word. It was a literal `<VisuallyHidden>Unread</VisuallyHidden>`, which no `strings` override could reach and no consumer could translate.
 
@@ -145,7 +151,7 @@ Nothing to change when passing a partial, which is what the `strings` prop takes
 
 ### `typography written into JSX`
 
-**Becomes** `CommentsStrings.formatQuoteAttribution and MentionInlineSuggestionsStrings.formatQuery` — mechanical, the codemod does it.
+**Becomes** `CommentsStrings.formatQuoteAttribution and MentionInlineSuggestionsStrings.formatQuery` — a direct rename, by hand.
 
 The em dash before a quoted block's attribution, and the curly quotes around a search term, were written into the JSX. Neither is punctuation every language shares — German sets „…“ and French « … » — so a consumer could translate every key in both interfaces and still be left with English convention.
 
@@ -163,7 +169,7 @@ Install @tiptap/core, @tiptap/pm and @tiptap/starter-kit when importing RichText
 
 **Becomes** `FilterStrings.applying / savedViews / customView and ActivitiesStrings.refreshing / error / refreshError / retry` — by hand.
 
-Pending filters, saved-view selects, and activity loading/retry states now expose their copy through the owning family's strings contract.
+Pending filters, saved-view selects, and activity loading/retry states now expose their copy through the owning module's strings contract.
 
 Partial strings overrides continue to work without changes. Complete FilterStrings maps must add applying (Updating results…), savedViews (Saved views), and customView (Custom view). Complete ActivitiesStrings maps must add refreshing (Updating activity…), error (Could not load activity), refreshError (Could not update activity), and retry (Try again). Spread the respective default strings before overrides to retain fallback copy. DataView's new optional strings.filterError controls its own matching-failure warning.
 
@@ -203,13 +209,13 @@ Nothing to change for ordinary use: every member these types had is still there
 
 **Becomes** `The component each one always was, under its own name: Overlay, OverlayTrigger, OverlayClose, OverlayBody, OverlayTitle, OverlayDescription, OverlayDismissArea and OverlayRootProps from base/overlay (for every Dialog*, Sheet* and AlertDialog* name above, and DialogProps); OverlayHeader and OverlayFooter from base/overlay (for every *Header and *Footer above); DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuGroup, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent and DropdownMenuPortal from base/dropdown-menu, around MenubarTrigger; AsideNavShell and AsideNavShellProps from layout/settings; Toggle and ToggleProps from base/toggle; CommandDialogProps declared against OverlayRootProps (the same members)` — by hand.
 
-Each removed name was `export const X = Y` of another kit component (or `type X = Y`): the same function under a second name, so there were two names to learn for one thing and every page documented it twice. A preset family now exports only the parts that set something. DialogContent fixes placement; SheetContent fixes an edge and a default shape; AlertDialogContent fixes role and dismissal, and AlertDialogAction and AlertDialogCancel name the answers; AlertDialogMedia is the media slot; MenubarTrigger draws a menu's word in the bar. The root, trigger, close, body, title and description around them are Overlay's own parts, and a menubar's menus are the dropdown menu's. The header and footer parts were OverlayHeader and OverlayFooter with an extra class (dialog--header, sheet--footer, …) that no stylesheet in the kit read, so they went with the aliases.
+Each removed name was `export const X = Y` of another kit component (or `type X = Y`): the same function under a second name, so there were two names to learn for one thing and every page documented it twice. A preset module now exports only the parts that set something. DialogContent fixes placement; SheetContent fixes an edge and a default shape; AlertDialogContent fixes role and dismissal, and AlertDialogAction and AlertDialogCancel name the answers; AlertDialogMedia is the media slot; MenubarTrigger draws a menu's word in the bar. The root, trigger, close, body, title and description around them are Overlay's own parts, and a menubar's menus are the dropdown menu's. The header and footer parts were OverlayHeader and OverlayFooter with an extra class (dialog--header, sheet--footer, …) that no stylesheet in the kit read, so they went with the aliases.
 
 Import the replacement under its own name; props and behaviour are identical because it was always the same component. `import { Dialog, DialogTrigger, DialogContent, DialogTitle } from "themelia-ui/base/dialog"` becomes `import { Overlay, OverlayTrigger, OverlayTitle } from "themelia-ui/base/overlay"` beside `import { DialogContent } from "themelia-ui/base/dialog"`, and `<Dialog>` becomes `<Overlay>`, `<DialogTitle>` `<OverlayTitle>`, and so on; Sheet* and AlertDialog* names map the same way (Sheet → Overlay, SheetClose → OverlayClose, AlertDialogBody → OverlayBody), and DialogDismissArea is OverlayDismissArea. In a Menubar, wrap each menu in `DropdownMenu` instead of `MenubarMenu`, keep `MenubarTrigger`, and swap every other `Menubar<Part>` for `DropdownMenu<Part>` from themelia-ui/base/dropdown-menu; import themelia-ui/base/dropdown-menu.css beside base/menubar.css, since the menubar sheet no longer pulls it in. `SettingsShell` becomes `AsideNavShell` and `ToggleGroupItem` becomes `Toggle` (give it the same `value`), both from the same subpath. `DialogHeader`, `SheetHeader` and `AlertDialogHeader` become `OverlayHeader`, and the three footers `OverlayFooter`; a stylesheet of your own that targeted `.dialog--header`, `.sheet--footer` or the alert-dialog pair should target `.overlay--header` / `.overlay--footer` inside `.dialog--component`, `.sheet--component` or `.alert-dialog--component` instead. Type annotations: DialogProps → OverlayRootProps, SettingsShellProps → AsideNavShellProps, ToggleGroupItemProps → ToggleProps. Code that typed CommandDialogProps needs nothing.
 
 ### `TextType including "discrete", Text type="discrete", and the --text-role-discrete role token; --text-role-secondary resolving to --foreground-80`
 
-**Becomes** `TextType without "discrete" — use type="secondary"; --text-role-secondary resolving to --muted-foreground; no --text-role-discrete` — mechanical, the codemod does it.
+**Becomes** `TextType without "discrete" — use type="secondary"; --text-role-secondary resolving to --muted-foreground; no --text-role-discrete` — a direct rename, by hand.
 
 Supporting text had four greys in play: Text secondary (--foreground-80), Text discrete, the modules' --muted-foreground and --foreground-80 set directly. A description and the metadata beside it came out rgb 84 against 99 in light and 204 against 161 in dark, which read as a mismatch rather than a hierarchy. Text now has two colours: the main one and --muted-foreground for everything supporting.
 
@@ -217,7 +223,7 @@ Replace type="discrete" with type="secondary" (the same grey now). A stylesheet
 
 ### `NavigationMenuContent side, sideOffset and container`
 
-**Becomes** `NavigationMenu side, sideOffset, align and container` — mechanical, the codemod does it.
+**Becomes** `NavigationMenu side, sideOffset, align and container` — a direct rename, by hand.
 
 Every NavigationMenuContent built its own portal, positioner and popup, so a bar of three entries mounted three panels: moving between entries swapped surfaces instead of resizing one, and each idle entry left a 0x0 popup whose ring shadow painted a dot. The bar now owns one shared panel and each content block is drawn into it, so placement is a property of the bar.
 
@@ -279,9 +285,57 @@ The provider wrote --duration-slow, which no stylesheet declares or reads, so th
 
 Remove durations.slow from your provider config.
 
+### `Scope as`
+
+**Becomes** `Scope render` — by hand.
+
+Every component that can become a different element takes `render`; `Scope` took `as`. See docs/adr/0005-polymorphic-render-contract.md.
+
+`<Scope vars={vars} as="section">` becomes `<Scope vars={vars} render={<section />}>`. `Scope` also passes the element's own props through (`id`, `aria-*`, `ref`), as `UIScope` does, and its props are exported as `ScopeProps`.
+
+### `LayoutLinkRenderer, LayoutLinkRenderProps`
+
+**Becomes** `LinkRenderer, LinkRenderProps` — by hand.
+
+Every component that renders a link takes one renderer shape, so one router adapter serves the whole kit; menus, pagination and table cells take it too, so it is not a layout type.
+
+Type the adapter as `LinkRenderer`, exported beside every component that takes `renderLink`. It returns one element rather than any node, and receives `aria-current` and `aria-disabled` to spread onto it along with the rest; `active`, `disabled` and `external` are hints to read, not to spread. `NavigationTabsProps`, `AppSidebarProps` and the other layout props take it unchanged, and `SidebarItemContext.renderLink`, which a custom `renderItem` receives, is one too.
+
+### `ActionLinkRenderer, ActionLinkRenderProps`
+
+**Becomes** `LinkRenderer, LinkRenderProps` — by hand.
+
+The action menu, the action buttons and a card's actions took a renderer shape of their own, so an application needed a second adapter for them.
+
+Pass the same `LinkRenderer` the layout takes to `ActionMenuProps.renderLink`, `ActionButtonsProps.renderLink` and `CardActionStripProps.renderLink`.
+
+### `Pagination renderLink(page, props)`
+
+**Becomes** `Pagination pageHref and renderLink(props)` — by hand.
+
+A pager's links take the same renderer as every other component; the page number becomes an address through `pageHref` instead.
+
+`renderLink={(page, props) => <Link href={`?page=${page}`} {...props} />}` becomes `pageHref={(page) => `?page=${page}`}`, which makes every control a link by itself, plus `renderLink` when the link goes through a router: `PaginationProps.renderLink` receives the href already built. `PaginationLinkProps` is gone.
+
+### `ResourceCellLinkProps and SideNav's renderLink props`
+
+**Becomes** `LinkRenderProps` — by hand.
+
+A table's resource cell and the side navigation took renderer shapes of their own.
+
+Type the renderer passed to `ResourceCellProps.renderLink` or `SideNavProps.renderLink` as `LinkRenderer`. A disabled `SideNav` entry arrives with `disabled` and renders without a destination.
+
+### `null for a variant prop on Badge, Alert, Item, ItemMedia, InputGroupAddon and InputGroupButton`
+
+**Becomes** `the prop left out` — by hand.
+
+Props typed from a variant map are declared, so their types no longer include null.
+
+Leave the prop out for the default: `Badge`'s `tone` and `variant` (and a metadata value's `badgeTone` and `badgeVariant`), `Alert`'s `tone` and `variant`, `Item`'s `surface`, `ItemMedia`'s `variant`, `InputGroupAddon`'s `align` and `InputGroupButton`'s `size`.
+
 ## CSS imports and tokens
 
-One stylesheet became one per family, and the token surface lost every name that restated another. Each token table below is applied by the codemod; a name marked removed is reported, never guessed at.
+One stylesheet became one per module, and the token surface lost every name that restated another. Each token table below is applied by the codemod; a name marked removed is reported, never guessed at.
 
 ### `themelia-ui/style.css`
 
@@ -289,7 +343,7 @@ One stylesheet became one per family, and the token surface lost every name that
 
 One stylesheet meant every consumer shipped every component's rules. The split means you ship what you import.
 
-Import each family's stylesheet beside its components; the family sheet imports `core.css` and its cascade layer order itself. `docs/generated/imports.md` lists every exact path. `style.css` still exists as the deduplicated union if you would rather not track them.
+Import each module's stylesheet beside its components; the module sheet imports `core.css` and its cascade layer order itself. `docs/generated/imports.md` lists every exact path. `style.css` still exists as the deduplicated union if you would rather not track them.
 
 ### `--radius-surface, --radius-popup, --radius-control, --radius-inner, --radius-md, --radius-lg, --radius-xl, --radius-2xl, --radius-3xl and --radius-4xl; --radius-sm as calc(var(--radius) * 0.375)`
 
@@ -400,9 +454,9 @@ The codemod renames the width and toolbar tokens. Set --shell-header-height (3.5
 
 ### `--medallion-base with --accordion-medallion, --choice-card-icon-box and --choice-card-row-icon; --switch-track-h; --menu-shadow and --menu-ring-width; --sidebar-group-action-size and --sidebar-menu-action-size; --button-px, --button-px-icon, --button-gap, --button-icon, --button-text, --toast-icon, --sidebar-menu-text, --accordion-media-gap; --badge-destructive-bg and the --destructive-60 alpha step only it read`
 
-**Becomes** `--size-medallion (IconBadge's --icon-badge-size defaults to it); --choice-size; --popover-shadow and --border-width; --sidebar-action-size; --control-px, --control-px-sm (for --button-px-icon), --space-sm, --size-icon, --text-sm, --size-icon-lg and --space-lg read directly; --badge-destructive-bg and --destructive-60 removed (nothing read them); use color-mix(in oklab, var(--destructive) 60%, transparent) if you relied on the step` — mechanical, the codemod does it.
+**Becomes** `--size-medallion (IconBadge's --icon-badge-size defaults to it); --choice-size; --popover-shadow and --border-width; --size-icon-lg; --control-px, --control-px-sm (for --button-px-icon), --space-sm, --size-icon, --text-sm, --size-icon-lg and --space-lg read directly; --badge-destructive-bg and --destructive-60 removed (nothing read them); use color-mix(in oklab, var(--destructive) 60%, transparent) if you relied on the step` — mechanical, the codemod does it.
 
-Each restated another token's derivation under a family name: the medallion four times from one base, the switch track the checkbox box, the dropdown menu the popover's shadow and hairline, two sidebar actions one size, and the button, toast, sidebar and accordion renamed kit steps with a bare var(). One name per value.
+Each restated another token's derivation under a component's name: the medallion four times from one base, the switch track the checkbox box, the dropdown menu the popover's shadow and hairline, two sidebar actions one size, and the button, toast, sidebar and accordion renamed kit steps with a bare var(). One name per value.
 
 Replace each name with its target where you override it. To retune the medallion everywhere, set --size-medallion; IconBadge alone still takes --icon-badge-size.
 
@@ -415,8 +469,8 @@ Replace each name with its target where you override it. To retune the medallion
 | `--switch-track-h` | `--choice-size` |
 | `--menu-shadow` | `--popover-shadow` |
 | `--menu-ring-width` | `--border-width` |
-| `--sidebar-group-action-size` | `--sidebar-action-size` |
-| `--sidebar-menu-action-size` | `--sidebar-action-size` |
+| `--sidebar-group-action-size` | `--size-icon-lg` |
+| `--sidebar-menu-action-size` | `--size-icon-lg` |
 | `--button-px` | `--control-px` |
 | `--button-px-icon` | `--control-px-sm` |
 | `--button-gap` | `--space-sm` |
@@ -481,6 +535,75 @@ The codemod renames --space-scale; a rule that set both factors now sets --densi
 | `--space-scale` | `--density-scale` |
 | `--density-preset-scale` | `--density-scale` |
 
+### `--card-framed-bg, --alert-description-fg, --alert-link-hover, --alert-meta-label-fg, --mention-destructive-fg, --menu-item-destructive-bg-hover and --segmented-chip-bg`
+
+**Becomes** `--card, --text-role-secondary, --text-role-main, --text-role-secondary, --destructive-accent, --destructive-10 and --popover, read directly` — mechanical, the codemod does it.
+
+Each was one component's colour for a role the kit already names, and several carried a dark value of their own. The framed Card lifted itself to --popover in dark while every other card-like surface sat on --card; the inverse Alert kept three names for its text where re-pointing the text roles does the job; the destructive mention and menu highlight mixed their own ink and wash. Each role has one token now: cards paint --card, destructive ink is --destructive-accent, its soft fill --destructive-10, and the raised segmented chip --popover.
+
+The codemod renames each read. A declaration that restyled one component now sets a shared name, so move it onto that component's element rather than a scope or :root. A dark lift for cards belongs in the theme's --card.
+
+| was | is |
+| --- | --- |
+| `--card-framed-bg` | `--card` |
+| `--alert-description-fg` | `--text-role-secondary` |
+| `--alert-link-hover` | `--text-role-main` |
+| `--alert-meta-label-fg` | `--text-role-secondary` |
+| `--mention-destructive-fg` | `--destructive-accent` |
+| `--menu-item-destructive-bg-hover` | `--destructive-10` |
+| `--segmented-chip-bg` | `--popover` |
+
+### `--aside-nav-item-h, --avatar-group-ring-width, --item-title-underline-offset, --product-thumb-size, --stepper-line, --timeline-dot-icon and --tooltip-arrow-radius`
+
+**Becomes** `--control-h-sm, --border-width-strong, --link-underline-offset, --size-medallion, --border-width-strong and --size-icon-sm, read directly; --tooltip-arrow-radius removed, since an arrow tip is calc(var(--radius-sm) / 4)` — mechanical, the codemod does it.
+
+Each restated a kit length under a component name, or was a third radius. SideNav and SectionNav rows had a 30px literal that is the small control height at the defaults; the avatar group ring and the Stepper line are the strong border width; the product thumbnail is the head-of-row medallion; the item title's 4px underline offset joins the one link offset; the Timeline dot's icon is the small icon; and the tooltip arrow kept a radius the two-radius system has no room for.
+
+The codemod renames each read. --tooltip-arrow-radius is reported, not renamed: write calc(var(--radius-sm) / 4) where you read it.
+
+| was | is |
+| --- | --- |
+| `--aside-nav-item-h` | `--control-h-sm` |
+| `--avatar-group-ring-width` | `--border-width-strong` |
+| `--item-title-underline-offset` | `--link-underline-offset` |
+| `--product-thumb-size` | `--size-medallion` |
+| `--stepper-line` | `--border-width-strong` |
+| `--timeline-dot-icon` | `--size-icon-sm` |
+| `--tooltip-arrow-radius` | removed — reported |
+
+### `--primary-12, --success-15, --info-15, --info-40, --warning-50, --muted-30, --muted-35, --border-50 and --border-70`
+
+**Becomes** `--primary-10, --success-10, --info-10, --info-30, --warning-10, --muted-50, --muted-20, --border-60 and --border, read directly` — mechanical, the codemod does it.
+
+Each alpha step had a handful of readers that were drifting copies of another role. Soft tone washes are the 10% step in every hue; the muted ladder is a recessed well (--muted-50) and a faint stripe (--muted-20); and an edge is either the full --border or the soft --border-60 divider. The 12%, 15% and 50% washes, the 30% and 35% wells and the 50% and 70% edges had no role of their own.
+
+The codemod renames each read. The mapping keeps the role, not the exact alpha: a 12-15% wash becomes 10%, a 50% warning fill becomes the 10% wash, and a 70% edge becomes the full border. If you relied on the old step, write color-mix(in oklab, var(--<colour>) <n>%, transparent) where you read it.
+
+| was | is |
+| --- | --- |
+| `--primary-12` | `--primary-10` |
+| `--success-15` | `--success-10` |
+| `--info-15` | `--info-10` |
+| `--info-40` | `--info-30` |
+| `--warning-50` | `--warning-10` |
+| `--muted-30` | `--muted-50` |
+| `--muted-35` | `--muted-20` |
+| `--border-50` | `--border-60` |
+| `--border-70` | `--border` |
+
+### `--sidebar-action-size and --picker-clear-size`
+
+**Becomes** `--size-icon-lg and --size-icon, read directly` — mechanical, the codemod does it.
+
+Glyph buttons below the smallest control came in four sizes. There are two now: a button inside a field's own lane is the icon size (16px at the defaults), and every other glyph button is the large icon size (20px). The Sidebar's group and menu actions already rendered 20px through a literal of their own, and the date picker's clear button 16px through a sum.
+
+The codemod renames each read. Retune the sizes kit-wide with --icon, or set width and height on the button itself.
+
+| was | is |
+| --- | --- |
+| `--sidebar-action-size` | `--size-icon-lg` |
+| `--picker-clear-size` | `--size-icon` |
+
 ## Behaviour changes
 
 Same name, same signature, a different answer — the kind of change a type checker cannot warn you about.
@@ -553,7 +676,7 @@ Nothing, unless a layout of yours assumed the 90vw cap on phones.
 
 **Becomes** `removed` — by hand.
 
-They matched classes no component renders — leftovers from the Tailwind source kit.
+They matched classes no component renders.
 
 If you passed border-b or border-t to an addon for its padding, set the padding yourself.
 
@@ -588,3 +711,31 @@ Remove any --row-y-sm or --row-y-lg you set; size the rows with size or density.
 The carousel scrolled to a slide's offsetLeft, which RTL clamps to 0, so next did nothing; the index compared offsets that only increase in LTR.
 
 Nothing; RTL carousels now navigate.
+
+### `A CommonJS build behind the require condition, carrying no stylesheet imports`
+
+**Becomes** `ES modules only` — by hand.
+
+The CommonJS build doubled every entry and declaration file. With no stylesheet imports in the JavaScript, Node loads the ES modules as they are.
+
+Import the package from ES modules; CommonJS code on Node 20.19 or later can `require()` it. In Jest, exempt it in `transformIgnorePatterns`.
+
+### `JavaScript entries that imported their own stylesheets`
+
+**Becomes** `JavaScript that imports no CSS, with each module's stylesheet imported beside it` — by hand.
+
+One way to load the styles. A bundler could drop a stylesheet together with an unused re-export module, and Node could not run an entry that imported one.
+
+Import each module's stylesheet beside its JavaScript, as in `import "themelia-ui/base/buttons.css"`, or `themelia-ui/style.css` once; a component whose stylesheet is not imported renders unstyled. `ssr.noExternal` and `test.server.deps.inline` entries added for the kit can go.
+
+## Data files and the component finder
+
+The machine-readable files the package ships, and the flags of the finder that reads them.
+
+### `component-index.json schema 2: families, layer, dependsOnFamilies`
+
+**Becomes** `component-index.json schema 3: modules, tier, dependsOn` — by hand.
+
+The published catalogue uses the documentation's words: modules, grouped in six tiers.
+
+Read `modules` instead of `families`, `tier` instead of `layer` (foundations, primitives, base, layout, features or blocks) and `dependsOn` instead of `dependsOnFamilies`. In recipes.json read `module`, `modules` and `supportingModules`; in the profile records read `modules`. Pass `--module=` and `--tier=` to find-component.mjs.