themelia-ui 3.0.0 → 3.2.0

package/docs/generated/migration.md

@@ -19,55 +19,55 @@ worse than no codemod.
 
 ## Moved subpaths
 
-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.
+Modules that moved to another subpath. 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`
+### `@/services/actions`
 
-**Becomes** `themelia-ui/patterns/analytics` — mechanical, the codemod does it.
+**Becomes** `themelia-ui/features/actions` — mechanical, the codemod does it.
 
-`blocks/` became `patterns/`, and the admin domains moved under `admin/patterns/`. The tier kept its position above Features; only the subpath changed.
+The action registry was never published; it lived at a source alias no consumer could resolve. It is a module now.
 
-### `themelia-ui/blocks/onboarding`
+### `themelia-ui/features/suggestions`
 
-**Becomes** `themelia-ui/patterns/onboarding` — mechanical, the codemod does it.
+**Becomes** `themelia-ui/features/combobox` — mechanical, the codemod does it.
 
-See above.
+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. Styles arrive with the new module import.
 
-### `themelia-ui/blocks/timelines`
+### `themelia-ui/styles`
 
-**Becomes** `themelia-ui/patterns/timelines` — mechanical, the codemod does it.
+**Becomes** `themelia-ui/core.css` — mechanical, the codemod does it.
 
-See above.
+The JavaScript imports no CSS, so the entry that only imported the core stylesheet is gone; import the stylesheet itself.
 
-### `themelia-ui/blocks/access`
+### `themelia-ui/patterns/analytics`
 
-**Becomes** `themelia-ui/admin/patterns/access` — mechanical, the codemod does it.
+**Becomes** `themelia-ui/blocks/analytics` — mechanical, the codemod does it.
 
-Admin domains moved into the admin profile, which may build on general modules but never the reverse.
+The tier above Features is Blocks everywhere else: in the documentation, the component index and the finder. Its subpaths now say so too, and the admin blocks sit inside it at `blocks/admin/`.
 
-### `themelia-ui/blocks/commerce`
+### `themelia-ui/patterns/onboarding`
 
-**Becomes** `themelia-ui/admin/patterns/commerce` — mechanical, the codemod does it.
+**Becomes** `themelia-ui/blocks/onboarding` — mechanical, the codemod does it.
 
 See above.
 
-### `@/services/actions`
+### `themelia-ui/patterns/timelines`
 
-**Becomes** `themelia-ui/features/actions` — mechanical, the codemod does it.
+**Becomes** `themelia-ui/blocks/timelines` — mechanical, the codemod does it.
 
-The action registry was never published; it lived at a source alias no consumer could resolve. It is a module now.
+See above.
 
-### `themelia-ui/features/suggestions`
+### `themelia-ui/admin/patterns/access`
 
-**Becomes** `themelia-ui/features/combobox` — mechanical, the codemod does it.
+**Becomes** `themelia-ui/blocks/admin/access` — mechanical, the codemod does it.
 
-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.
+See above.
 
-### `themelia-ui/styles`
+### `themelia-ui/admin/patterns/commerce`
 
-**Becomes** `themelia-ui/core.css` — mechanical, the codemod does it.
+**Becomes** `themelia-ui/blocks/admin/commerce` — 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.
+See above.
 
 ## Provider changes
 
@@ -105,10 +105,74 @@ Enable forms.preventIPhoneZoom explicitly to apply a 16px minimum to native fiel
 
 Set radiusSm beside radius when you want controls to change with containers.
 
+### `UIConfig.theme.colors keys link-color, inverse-background, inverse-foreground, inverse-surface, inverse-surface-strong, inverse-muted, inverse-subtle, inverse-border, inverse-decoration, inverse-disabled, primary-accent, destructive-accent, warning-accent, sidebar-primary and sidebar-primary-foreground (SemanticToken)`
+
+**Becomes** `the theme's 38 colours: link instead of link-color, and overlay-backdrop` — by hand.
+
+The theme is one level of variables, each colour a light-dark() pair. An inverse region is a colour island rather than a second set of names, a tone's text colour comes from the tone rule, and the sidebar's current item takes --sidebar-accent.
+
+Rename `link-color` to `link`. For an inverse region, nest a provider with `config={{ colorScheme: "dark" }}` and drop the `inverse-*` keys. Drop the `*-accent` keys: a component with a `tone` colours its text from it. Move a `sidebar-primary` value to `sidebar-accent`.
+
+### `MotionConfig.durations.instant`
+
+**Becomes** `MotionConfig.durations.fast` — by hand.
+
+Two durations: `fast` for state changes, `normal` for entrances. Every use of the instant step read as a state change.
+
+Write an `instant` value as `fast`, or drop it.
+
+### `ThemeConfig.palette (UIConfig.theme.palette) and the PaletteToken type`
+
+**Becomes** `theme.colors` — by hand.
+
+The palette is gone: each theme colour is its own light-dark() pair, so there is no ramp for the colours to resolve through.
+
+Set the theme colour of the same role through `theme.colors`, as a `light-dark(light, dark)` pair when the modes differ.
+
 ## Prop changes
 
 One idea that had two spellings.
 
+### `ColorInputProps.emitHex`
+
+**Becomes** `ColorInputProps.format="hex"` — a direct rename, by hand.
+
+One output format had two prop spellings.
+
+Replace emitHex with format="hex" on ColorInput.
+
+### `AnalyticsStrings.metricInfoLabel and AsyncComboboxStrings.removeChip`
+
+**Becomes** `required translation keys` — by hand.
+
+A complete translation table must name the info control and each removable chip.
+
+Add metricInfoLabel and removeChip to complete AnalyticsStrings and AsyncComboboxStrings maps. Partial strings props continue to use defaults.
+
+### `MediaLibraryState optional recovery and selection controls`
+
+**Becomes** `required fetchError, refetch, selectVisible and deselectVisible` — by hand.
+
+The state contract includes every control the hook returns and the component reads.
+
+State adapters must implement all four members. useMediaLibrary supplies them.
+
+### `MediaLibraryStrings optional complete-translation keys`
+
+**Becomes** `required keys in complete translations` — by hand.
+
+Complete translation tables should cover every string the media library renders.
+
+Fill the new keys from defaultMediaLibraryStrings in complete translations; partial strings props may still override only what they need.
+
+### `createExecCommandEngine`
+
+**Becomes** `createTiptapEngine` — by hand.
+
+The browser command adapter is removed; TipTap is the editor engine.
+
+Use the built-in RichTextEditor engine or import createTiptapEngine from themelia-ui/features/rich-text-editor/tiptap for a custom schema.
+
 ### `asChild`
 
 **Becomes** `render` — by hand.
@@ -137,7 +201,7 @@ Nothing to change when passing a string or omitting the prop. Only a consumer wh
 
 **Becomes** `removed` — by hand.
 
-Each of these was declared in a `default*Strings` object and in its exported interface, and read by NOTHING. Overriding one did exactly nothing, silently, which is the worst shape an API can take — the caller has no way to tell it did not work. They accumulated the same way each time: the component owned a label, the design moved that copy to a prop the caller supplies or the feature went away, and the key stayed behind. Removed: `OrderCustomerStrings.viewCustomer`, `OrderSummaryStrings.formatItemCount`, `PaymentMethodStrings.holder`, `SeoStrings.scoreLabel`, `OverflowTabBarStrings.scrollHint`, `AiChatPromptInputStrings.modelPickerAria`, `CommentsStrings.moreActionsLabel`, `DataViewPaginationStrings.morePages`, `FilterStrings.selectDateRange`, `GlobalSearchStrings.idleRecent`, `GlobalSearchStrings.idleSuggestions`, `MediaLibraryStrings.retry`, `MediaLibraryStrings.usedIn`, `ProductVariantBulkTableStrings.optionLabel`, `SideNavStrings.toggleGroup`.
+Each of these was declared in a `default*Strings` object and in its exported interface, and read by nothing. Removed: `OrderCustomerStrings.viewCustomer`, `OrderSummaryStrings.formatItemCount`, `PaymentMethodStrings.holder`, `SeoStrings.scoreLabel`, `OverflowTabBarStrings.scrollHint`, `AiChatPromptInputStrings.modelPickerAria`, `CommentsStrings.moreActionsLabel`, `DataViewPaginationStrings.morePages`, `FilterStrings.selectDateRange`, `GlobalSearchStrings.idleRecent`, `GlobalSearchStrings.idleSuggestions`, `MediaLibraryStrings.usedIn`, `ProductVariantBulkTableStrings.optionLabel`, `SideNavStrings.toggleGroup`.
 
 Delete the override. The copy it appeared to control is either supplied by you already — a `sections[].label`, a slot, an item field — or is no longer rendered. Two keys from the same sweep went the other way and are NOT removed: `CredentialListStrings.copyLabel` now names each row's copy button, and `AiConfirmationStrings.detailsLabel` now names the confirmation's details region; both were unread for the opposite reason, and both are worth setting.
 
@@ -163,7 +227,7 @@ Nothing to change when passing a partial, which is what both `strings` props tak
 
 The default RichTextEditor now uses TipTap StarterKit with atomic mentions. TiptapEngineOptions.extensions now uses the public Extensions type; the previous conditional type incorrectly resolved to never with the installed optional constructor options.
 
-Install @tiptap/core, @tiptap/pm and @tiptap/starter-kit when importing RichTextEditor, comments or activities. Existing props and refs remain supported. HTML is normalized to the active schema; supply custom extensions to retain other content. Custom extension arrays replace StarterKit and the default mention node. Existing calls without extensions remain valid; consumers can now pass real TipTap extensions without a cast. The legacy createExecCommandEngine export remains available for explicit integrations.
+Install @tiptap/core, @tiptap/pm and @tiptap/starter-kit when importing RichTextEditor, comments or activities. HTML is normalized to the active schema; supply custom extensions to retain other content. Custom extension arrays replace StarterKit and the default mention node. Consumers can pass TipTap extensions directly.
 
 ### `Complete FilterStrings and ActivitiesStrings translation maps`
 
@@ -179,7 +243,7 @@ Partial strings overrides continue to work without changes. Complete FilterStrin
 
 Asset management needs both dense browsing and comparable metadata.
 
-Use view="list" for compact rows. Supply onUpload to show the upload tab, use helpers.files IDs for progress, and applyItemPatch when accessors read a custom record shape. New MediaLibraryStrings keys are optional for existing complete translations.
+Use view="list" for compact rows. Supply onUpload to show the upload tab, use helpers.files IDs for progress, and applyItemPatch when accessors read a custom record shape. Add the new keys to complete MediaLibraryStrings translations.
 
 ### `Slider, SliderField, SliderProps, SliderFieldProps and SliderChangeEvent with never-valued callbacks or scalar-only events`
 
@@ -333,17 +397,169 @@ Props typed from a variant map are declared, so their types no longer include nu
 
 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`.
 
+### `buttonStyle on Button, TextButton, LoaderButton, TooltipButton, ToolbarButton (ToolbarButtonProps) and every other component that forwards Button props; buttonStyle in action definitions (ActionDefinition) and ActionPresentation; the ButtonStyle and ActionButtonStyle types`
+
+**Becomes** `appearance, with the ButtonAppearance and ActionAppearance types` — by hand.
+
+Fill style had three names: `buttonStyle` on buttons and actions, `variant` on Badge and Toggle. It is `appearance` everywhere now, so `tone` is always colour, `appearance` always fill and `variant` always structure.
+
+Rename the prop: `<Button buttonStyle="outline">` becomes `<Button appearance="outline">`, and `{ buttonStyle: "ghost" }` in an action definition becomes `{ appearance: "ghost" }`. Provider defaults move with it: `defaults: { button: { appearance: "ghost" } }`. Button renders `data-appearance` instead of `data-style`; update CSS that selects it.
+
+### `variant on Badge (soft, solid, outline), the BadgeVariant type, the badgeVariants class function, and badgeVariant on a metadata badge value`
+
+**Becomes** `appearance, BadgeAppearance, Badge itself, and badgeAppearance` — by hand.
+
+See the Button entry.
+
+`<Badge variant="solid">` becomes `<Badge appearance="solid">`; a metadata value `{ kind: "badge", badgeVariant }` becomes `{ kind: "badge", badgeAppearance }`. `badgeVariants` is gone: its colours came from a class, and a badge now takes its colour from the tone it carries. For a badge that links, render one: `<Badge render={<a href="/queue" />}>Queued</Badge>`.
+
+### `variant on Toggle (ToggleProps: ghost, outline) and SidebarMenuButton (SidebarMenuButtonProps: default, outline)`
+
+**Becomes** `appearance` — by hand.
+
+See the Button entry.
+
+`<Toggle variant="outline">` becomes `<Toggle appearance="outline">`, and Toggle renders `data-appearance` instead of `data-variant`; `<SidebarMenuButton variant="outline">` becomes `<SidebarMenuButton appearance="outline">`.
+
+### `confirmStyle on ActionDialog, ActionSheet and ConfirmDialog (OverlayActionProps) and on an action modality (ActionModalityConfig), and the OverlayButtonStyle type`
+
+**Becomes** `confirmAppearance and OverlayButtonAppearance` — by hand.
+
+See the Button entry.
+
+`confirmStyle="outline"` becomes `confirmAppearance="outline"`.
+
+### `gap, rowGap, columnGap and amount on Stack, Grid, AdaptiveGrid, Split and Bleed (StructureGap: 2xs, xs, sm, md, lg, xl, 2xl)`
+
+**Becomes** `StructureGap: none, sm and default` — by hand.
+
+Two gaps: `default` between groups, `sm` inside a group. Every scale has two steps: a default and a smaller one. A size, padding or gap prop offers `default` and `sm`; a step larger than the default is gone.
+
+`2xs`, `xs`, `sm` and `md` become `sm` (8px); `lg`, `xl` and `2xl` become `default` (16px), which is also what an unset gap is. An unset Stack or Split gap was 8px and is now 16px: write `gap="sm"` to keep the tighter one.
+
+### `maxWidth on Stack and Grid (StackProps, GridProps) and sideWidth on Split (SplitProps): StructureWidth sm, md, lg, xl and 2xl, or any string`
+
+**Becomes** `StructureWidth default, sm, full and none, or a CssLength` — by hand.
+
+Every scale has two steps: a default and a smaller one. A size, padding or gap prop offers `default` and `sm`; a step larger than the default is gone. A free string no longer type-checks, so a misspelt step cannot pass as a length.
+
+`lg` becomes `default` (the content width) and `sm` stays; for `md`, `xl` or `2xl` pass the length itself, such as `"48rem"`. A length is a number with a unit, a percentage, or a `calc()`, `min()`, `max()`, `clamp()` or `var()` expression.
+
+### `minColumnWidth on AdaptiveGrid (AdaptiveGridProps, AdaptiveGridMinimum: sm, md, lg)`
+
+**Becomes** `default, sm or a CssLength` — by hand.
+
+Every scale has two steps: a default and a smaller one. A size, padding or gap prop offers `default` and `sm`; a step larger than the default is gone.
+
+`md` becomes `default` (16rem) and `sm` stays (12rem); for `lg` pass `"20rem"`.
+
+### `ComponentScale (sm, md, lg): Spinner size, Empty padding (EmptyPadding), DataTable size (DataTableSize) and ResourceDetailsSection padding (ResourceBlockPadding)`
+
+**Becomes** `ComponentScale: default and sm` — by hand.
+
+Every scale has two steps: a default and a smaller one. A size, padding or gap prop offers `default` and `sm`; a step larger than the default is gone.
+
+`md` becomes `default`, which is what an unset prop is, and `sm` stays. `lg` is gone: leave the prop out. A comfortable provider density no longer widens a DataTable, because the density preset already widens its insets.
+
+### `size="lg" on Avatar (AvatarSize), SidebarMenuButton (SidebarMenuButtonSize) and AuthShell (AuthShellSize); md on SidebarMenuButton, SidebarMenuSubButton (SidebarMenuSubButtonProps) and AuthShell`
+
+**Becomes** `default and sm` — by hand.
+
+Every scale has two steps: a default and a smaller one. A size, padding or gap prop offers `default` and `sm`; a step larger than the default is gone. A sidebar row that holds a workspace or an account (an avatar over two lines) takes its height from AppSidebar.
+
+`md` becomes `default`; remove `size="lg"`.
+
+### `size on Slider and SliderField (SliderFieldProps)`
+
+**Becomes** `no size prop` — by hand.
+
+A slider is dragged, so it sizes itself to the pointer: under a finger the track and thumb grow into a larger target.
+
+Remove `size`.
+
+### `size on InputGroupButton (InputGroupButtonProps: xs, sm, icon-xs, icon-sm)`
+
+**Becomes** `one size, and iconOnly for a square button` — by hand.
+
+Every scale has two steps: a default and a smaller one. A size, padding or gap prop offers `default` and `sm`; a step larger than the default is gone. A button inside a field has one size that fits it.
+
+Remove `size="xs"` and `size="sm"`; replace `size="icon-xs"` and `size="icon-sm"` with `iconOnly`.
+
+### `size on an overlay, SheetContent and ActionSheet (OverlaySize: sm, md, lg, full or any string); size, length and inset on ActionSheet (ActionSheetProps) as any string; OverlayLength and OverlayInset as any string`
+
+**Becomes** `OverlaySize: default, sm, full or a CssLength; OverlayLength and OverlayInset take a CssLength` — by hand.
+
+Every scale has two steps: a default and a smaller one. A size, padding or gap prop offers `default` and `sm`; a step larger than the default is gone. A free string no longer type-checks, so a misspelt step cannot pass as a length.
+
+`md` becomes `default`, which is what an unset size is, and `sm` and `full` stay; for `lg` pass a length such as `"90%"`.
+
+### `size on an action modality (ActionModalityConfig) and the ActionOverlaySize type`
+
+**Becomes** `removed` — by hand.
+
+The size was never read: no dialog, sheet or drawer took its width from it.
+
+Remove `size` from the modality. Size an action sheet through ActionSheet’s own `size`.
+
+### `density on MetadataList (MetadataDensity: default, compact) and its data-row-density attribute`
+
+**Becomes** `size (MetadataSize: default, sm) and data-size` — by hand.
+
+`density` belongs to the provider; a component prop that sets a rhythm is a size.
+
+`density="compact"` becomes `size="sm"`; CSS that selects `[data-row-density="compact"]` selects `[data-size="sm"]`.
+
+### `density on ActivityFeed, ActivityRow and ActivityMarker (ActivityFeedProps, ActivityRowProps, ActivityMarkerProps, ActivityRenderRowContext, ActivityDensity) and data-activity-density`
+
+**Becomes** `variant (ActivityVariant: compact, default, rich) and data-variant` — by hand.
+
+`density` belongs to the provider. This one decides how much of a row is drawn, which is a variant.
+
+Rename `density` to `variant`, `ActivityDensity` to `ActivityVariant`, and a row renderer’s `context.density` to `context.variant`; CSS that selects `[data-activity-density]` selects `[data-variant]`.
+
+### `itemSpacing on ActivityFeed and ActivityLog (ActivityItemSpacing: compact, default, relaxed)`
+
+**Becomes** `ActivityItemSpacing: default and sm` — by hand.
+
+Every scale has two steps: a default and a smaller one. A size, padding or gap prop offers `default` and `sm`; a step larger than the default is gone.
+
+`compact` becomes `sm`; remove `relaxed`.
+
+### `density on MediaLibrary, MediaLibraryGrid, MediaLibraryCard and MediaResourceGallery (MediaLibraryProps, MediaLibraryGridProps, MediaLibraryCardProps, MediaResourceGalleryProps, MediaLibraryDensity: comfortable, compact) and data-media-density`
+
+**Becomes** `size (MediaLibrarySize: default, sm) and data-size` — by hand.
+
+`density` belongs to the provider; a prop that sets the tile size is a size.
+
+`density="comfortable"` becomes `size="default"` (or leave it out) and `density="compact"` becomes `size="sm"`; CSS that selects `[data-media-density="compact"]` selects `[data-size="sm"]`.
+
+### `density on AiTask (AiTaskProps: compact, expanded)`
+
+**Becomes** `defaultExpanded` — by hand.
+
+`density` belongs to the provider. This one decided whether nested sub-tasks start open.
+
+`density="expanded"` becomes `defaultExpanded`; remove `density="compact"`, which is the default.
+
+### `size="xxs" on Text (TextSize) and weight="regular" on Text (TextWeight), and typography.defaultTextSize "xxs"`
+
+**Becomes** `size="xs" and weight="normal"` — by hand.
+
+Two spellings of one value each: `xxs` rendered as `xs`, and `regular` as `normal`.
+
+Replace `xxs` with `xs` and `regular` with `normal`.
+
 ## CSS imports and tokens
 
 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`
 
-**Becomes** `one self-contained sheet per family` — by hand.
+**Becomes** `automatic CSS with component imports, or style.css for direct links` — by hand.
 
-One stylesheet meant every consumer shipped every component's rules. The split means you ship what you import.
+One stylesheet meant every consumer shipped every component's rules. Component imports now bring only their reachable CSS.
 
-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.
+In a bundled app, import the JavaScript subpaths and remove explicit kit stylesheet imports. For direct stylesheet links without a bundler, use style.css; see docs/learn/migration.md#upgrading-to-31.
 
 ### `--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)`
 
@@ -386,7 +602,7 @@ The codemod replaces --text-role-discrete with --text-role-secondary, so a surfa
 
 | was | is |
 | --- | --- |
-| `--text-role-discrete` | `--text-role-secondary` |
+| `--text-role-discrete` | `--muted-foreground` |
 | `--foreground-80` | `--muted-foreground` |
 
 ### `--menu-surface-p, --menu-row-px, --field-h, --field-px, --text-xxs and --text-xxs--line-height`
@@ -399,12 +615,12 @@ The codemod renames each token, and the text-xxs utility to text-xs — the Tail
 
 | was | is |
 | --- | --- |
-| `--menu-surface-p` | `--space-md` |
-| `--menu-row-px` | `--row-px` |
-| `--field-h` | `--control-h` |
-| `--field-px` | `--control-px-sm` |
+| `--menu-surface-p` | removed — reported |
+| `--menu-row-px` | `--padding-sm` |
+| `--field-h` | `--control-height` |
+| `--field-px` | removed — reported |
 | `--text-xxs` | `--text-xs` |
-| `--text-xxs--line-height` | `--text-xs--line-height` |
+| `--text-xxs--line-height` | removed — reported |
 | `text-xxs` (class) | `text-xs` |
 
 ### `--heading-fg, --heading-sub-fg, --display-label-fg and --link-fg`
@@ -417,10 +633,10 @@ Where you re-pointed these on an inverted or tinted surface, re-point --text-rol
 
 | was | is |
 | --- | --- |
-| `--heading-fg` | `--text-role-main` |
-| `--display-label-fg` | `--text-role-main` |
-| `--heading-sub-fg` | `--text-role-secondary` |
-| `--link-fg` | `--link-color` |
+| `--heading-fg` | `--foreground` |
+| `--display-label-fg` | `--foreground` |
+| `--heading-sub-fg` | `--muted-foreground` |
+| `--link-fg` | `--link` |
 
 ### `--height-action with --action, --action-sm and --action-2xs; --height-control with --control-h`
 
@@ -432,10 +648,10 @@ Replace --height-action with --height-control, --action with --control-h, --acti
 
 | was | is |
 | --- | --- |
-| `--height-action` | `--height-control` |
-| `--action` | `--control-h` |
-| `--action-sm` | `--control-h-sm` |
-| `--action-2xs` | `--control-h-2xs` |
+| `--height-action` | `--control-height` |
+| `--action` | `--control-height` |
+| `--action-sm` | `--control-height-sm` |
+| `--action-2xs` | removed — reported |
 
 ### `--shell-sidebar-width, --shell-sidebar-w (app shell), --workspace-sidebar-w (workspace) and Sidebar's own --sidebar-width; --shell-toolbar-h and the app shell's --shell-header-h literal`
 
@@ -450,7 +666,7 @@ The codemod renames the width and toolbar tokens. Set --shell-header-height (3.5
 | `--shell-sidebar-width` | `--sidebar-width` |
 | `--shell-sidebar-w` | `--sidebar-width` |
 | `--workspace-sidebar-w` | `--sidebar-width` |
-| `--shell-toolbar-h` | `--shell-header-h` |
+| `--shell-toolbar-h` | `--header-height` |
 
 ### `--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`
 
@@ -462,23 +678,23 @@ Replace each name with its target where you override it. To retune the medallion
 
 | was | is |
 | --- | --- |
-| `--medallion-base` | `--size-medallion` |
-| `--accordion-medallion` | `--size-medallion` |
-| `--choice-card-icon-box` | `--size-medallion` |
-| `--choice-card-row-icon` | `--size-medallion` |
-| `--switch-track-h` | `--choice-size` |
-| `--menu-shadow` | `--popover-shadow` |
+| `--medallion-base` | removed — reported |
+| `--accordion-medallion` | removed — reported |
+| `--choice-card-icon-box` | removed — reported |
+| `--choice-card-row-icon` | removed — reported |
+| `--switch-track-h` | removed — reported |
+| `--menu-shadow` | `--shadow-lg` |
 | `--menu-ring-width` | `--border-width` |
-| `--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` |
-| `--button-icon` | `--size-icon` |
+| `--sidebar-group-action-size` | removed — reported |
+| `--sidebar-menu-action-size` | removed — reported |
+| `--button-px` | removed — reported |
+| `--button-px-icon` | removed — reported |
+| `--button-gap` | removed — reported |
+| `--button-icon` | `--icon-size` |
 | `--button-text` | `--text-sm` |
-| `--toast-icon` | `--size-icon-lg` |
+| `--toast-icon` | removed — reported |
 | `--sidebar-menu-text` | `--text-sm` |
-| `--accordion-media-gap` | `--space-lg` |
+| `--accordion-media-gap` | removed — reported |
 | `--badge-destructive-bg` | removed — reported |
 | `--destructive-60` | removed — reported |
 
@@ -492,13 +708,13 @@ The codemod renames the first seven. It reports the last five without editing th
 
 | was | is |
 | --- | --- |
-| `--ai-avatar-size` | `--size-avatar-sm` |
+| `--ai-avatar-size` | removed — reported |
 | `--ai-shimmer-base` | `--muted-foreground` |
-| `--badge-destructive-ink` | `--destructive-accent` |
-| `--choice-list-marker` | `--choice-size` |
-| `--header-px` | `--space-xl` |
-| `--item-media-image` | `--size-medallion` |
-| `--upload-thumb` | `--size-medallion` |
+| `--badge-destructive-ink` | removed — reported |
+| `--choice-list-marker` | removed — reported |
+| `--header-px` | removed — reported |
+| `--item-media-image` | removed — reported |
+| `--upload-thumb` | removed — reported |
 | `--destructive-50` | removed — reported |
 | `--field-py` | removed — reported |
 | `--slide-panel` | removed — reported |
@@ -515,12 +731,12 @@ The codemod renames the six tokens. Rows and insets move by 2–4px; if a layout
 
 | was | is |
 | --- | --- |
-| `--table-cell-py` | `--space-lg` |
-| `--aside-nav-px` | `--space-md` |
-| `--auth-brand-gap` | `--space-md` |
-| `--repeater-gap` | `--space-lg` |
-| `--calendar-months-gap` | `--space-xl` |
-| `--skeleton-block-gap` | `--space-xl` |
+| `--table-cell-py` | removed — reported |
+| `--aside-nav-px` | removed — reported |
+| `--auth-brand-gap` | removed — reported |
+| `--repeater-gap` | removed — reported |
+| `--calendar-months-gap` | removed — reported |
+| `--skeleton-block-gap` | removed — reported |
 
 ### `--space-scale (gaps and padding) beside --density-scale (heights and rows), both derived at every boundary from --density-preset-scale; density-scaled lengths left fractional`
 
@@ -532,8 +748,8 @@ The codemod renames --space-scale; a rule that set both factors now sets --densi
 
 | was | is |
 | --- | --- |
-| `--space-scale` | `--density-scale` |
-| `--density-preset-scale` | `--density-scale` |
+| `--space-scale` | removed — reported |
+| `--density-preset-scale` | removed — reported |
 
 ### `--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`
 
@@ -546,11 +762,11 @@ The codemod renames each read. A declaration that restyled one component now set
 | 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` |
+| `--alert-description-fg` | `--muted-foreground` |
+| `--alert-link-hover` | `--foreground` |
+| `--alert-meta-label-fg` | `--muted-foreground` |
+| `--mention-destructive-fg` | removed — reported |
+| `--menu-item-destructive-bg-hover` | removed — reported |
 | `--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`
@@ -563,12 +779,12 @@ The codemod renames each read. --tooltip-arrow-radius is reported, not renamed:
 
 | 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` |
+| `--aside-nav-item-h` | `--control-height-sm` |
+| `--avatar-group-ring-width` | removed — reported |
+| `--item-title-underline-offset` | removed — reported |
+| `--product-thumb-size` | removed — reported |
+| `--stepper-line` | removed — reported |
+| `--timeline-dot-icon` | `--icon-size-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`
@@ -581,14 +797,14 @@ The codemod renames each read. The mapping keeps the role, not the exact alpha:
 
 | 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` |
+| `--primary-12` | removed — reported |
+| `--success-15` | removed — reported |
+| `--info-15` | removed — reported |
+| `--info-40` | removed — reported |
+| `--warning-50` | removed — reported |
+| `--muted-30` | `--muted` |
+| `--muted-35` | removed — reported |
+| `--border-50` | `--border` |
 | `--border-70` | `--border` |
 
 ### `--sidebar-action-size and --picker-clear-size`
@@ -601,8 +817,314 @@ The codemod renames each read. Retune the sizes kit-wide with --icon, or set wid
 
 | was | is |
 | --- | --- |
-| `--sidebar-action-size` | `--size-icon-lg` |
-| `--picker-clear-size` | `--size-icon` |
+| `--sidebar-action-size` | removed — reported |
+| `--picker-clear-size` | `--icon-size` |
+
+### `The 3.0 theme: a palette, alpha steps, a seven-step spacing ladder, control, icon and avatar ladders, derived role variables, dark twins and three scale factors`
+
+**Becomes** `About eighty theme variables declared once at :root, each colour a light-dark() pair, and every length, shadow, tint and duration in twos` — by hand.
+
+Components compute everything else where they use it, so an override anywhere reaches every reader below it, and a dark region inside a light page needs no second set of values. Two of each leaves no step for two neighbouring controls to disagree on.
+
+Run the codemod: it renames each variable with a successor and reports the rest. For a reported one, write a tint as `color-mix(in oklab, var(--primary) var(--tint), transparent)` (`--tint-strong` for a line); a spacing step as `--padding` or `--padding-sm` for an inset and `--gap` or `--gap-sm` between things; type through Text's `size`, `weight` and `lineHeight`; an inverse region as a nested provider with `colorScheme: "dark"`; a scale factor as the provider's `scale` or `typography.scale`; a palette step as the theme colour of the same role. A component's own variable is private now: set the theme variable it reads, or style the component through `className`.
+
+| was | is |
+| --- | --- |
+| `--accent-50` | `--accent` |
+| `--adaptive-grid-min-lg` | removed — reported |
+| `--adaptive-grid-min-md` | removed — reported |
+| `--adaptive-grid-min-sm` | removed — reported |
+| `--ai-shimmer-duration` | removed — reported |
+| `--animate-enter` | removed — reported |
+| `--animate-exit` | removed — reported |
+| `--animate-ping` | removed — reported |
+| `--animate-pulse` | removed — reported |
+| `--animate-spin` | removed — reported |
+| `--avatar` | removed — reported |
+| `--background-70` | removed — reported |
+| `--background-80` | removed — reported |
+| `--border-60` | `--border` |
+| `--border-width-strong` | removed — reported |
+| `--brand-300` | removed — reported |
+| `--brand-350` | removed — reported |
+| `--brand-600` | removed — reported |
+| `--brand-950` | removed — reported |
+| `--button-h` | removed — reported |
+| `--button-radius` | removed — reported |
+| `--card-px` | removed — reported |
+| `--card-py` | removed — reported |
+| `--chart-aspect` | removed — reported |
+| `--chart-indicator-color` | removed — reported |
+| `--choice-size` | removed — reported |
+| `--color-destructive-accent` | removed — reported |
+| `--color-inverse-background` | removed — reported |
+| `--color-inverse-border` | removed — reported |
+| `--color-inverse-decoration` | removed — reported |
+| `--color-inverse-disabled` | removed — reported |
+| `--color-inverse-foreground` | removed — reported |
+| `--color-inverse-muted` | removed — reported |
+| `--color-inverse-subtle` | removed — reported |
+| `--color-inverse-surface` | removed — reported |
+| `--color-inverse-surface-strong` | removed — reported |
+| `--color-primary-accent` | removed — reported |
+| `--color-sidebar-primary` | removed — reported |
+| `--color-sidebar-primary-foreground` | removed — reported |
+| `--color-warning-accent` | removed — reported |
+| `--content-block-p` | removed — reported |
+| `--content-width-2xl` | removed — reported |
+| `--content-width-lg` | `--content-width` |
+| `--content-width-md` | removed — reported |
+| `--content-width-sm` | removed — reported |
+| `--content-width-xl` | removed — reported |
+| `--control-border` | `--input` |
+| `--control-border-hover` | removed — reported |
+| `--control-h` | `--control-height` |
+| `--control-h-2xs` | removed — reported |
+| `--control-h-sm` | `--control-height-sm` |
+| `--control-px` | removed — reported |
+| `--control-px-2xs` | removed — reported |
+| `--control-px-sm` | removed — reported |
+| `--control-x` | removed — reported |
+| `--danger-400` | removed — reported |
+| `--danger-600` | removed — reported |
+| `--danger-950` | removed — reported |
+| `--data-table-body-max-height` | removed — reported |
+| `--density-scale` | removed — reported |
+| `--destructive-10` | removed — reported |
+| `--destructive-20` | removed — reported |
+| `--destructive-30` | removed — reported |
+| `--destructive-40` | removed — reported |
+| `--destructive-5` | removed — reported |
+| `--destructive-accent` | removed — reported |
+| `--duration-instant` | `--duration-fast` |
+| `--duration-normal` | `--duration` |
+| `--ease-in-out` | `--ease` |
+| `--ease-out` | `--ease` |
+| `--editor-min-h` | removed — reported |
+| `--editor-min-h-compact` | removed — reported |
+| `--empty-art-h` | removed — reported |
+| `--enter-opacity` | removed — reported |
+| `--enter-scale` | removed — reported |
+| `--enter-translate-x` | removed — reported |
+| `--enter-translate-y` | removed — reported |
+| `--exit-opacity` | removed — reported |
+| `--exit-scale` | removed — reported |
+| `--exit-translate-x` | removed — reported |
+| `--exit-translate-y` | removed — reported |
+| `--field-addon-lane` | removed — reported |
+| `--field-bg` | removed — reported |
+| `--field-focus-ring` | removed — reported |
+| `--field-icon-lane` | removed — reported |
+| `--field-label-width` | removed — reported |
+| `--field-min-font-size` | removed — reported |
+| `--focus-ring` | removed — reported |
+| `--focus-ring-color` | `--ring` |
+| `--focus-ring-inset` | removed — reported |
+| `--focus-ring-offset` | removed — reported |
+| `--focus-ring-width` | removed — reported |
+| `--font-serif` | removed — reported |
+| `--foreground-10` | removed — reported |
+| `--foreground-20` | removed — reported |
+| `--foreground-8` | removed — reported |
+| `--height-control` | `--control-height` |
+| `--hit-area-min` | removed — reported |
+| `--icon` | `--icon-size` |
+| `--info-10` | removed — reported |
+| `--info-30` | removed — reported |
+| `--info-400` | removed — reported |
+| `--info-5` | removed — reported |
+| `--info-600` | removed — reported |
+| `--info-950` | removed — reported |
+| `--input-30` | removed — reported |
+| `--invalid-ring` | removed — reported |
+| `--invalid-ring-border` | removed — reported |
+| `--invalid-ring-color` | removed — reported |
+| `--inverse-background` | removed — reported |
+| `--inverse-border` | removed — reported |
+| `--inverse-decoration` | removed — reported |
+| `--inverse-disabled` | removed — reported |
+| `--inverse-foreground` | removed — reported |
+| `--inverse-muted` | removed — reported |
+| `--inverse-subtle` | removed — reported |
+| `--inverse-surface` | removed — reported |
+| `--inverse-surface-strong` | removed — reported |
+| `--item-media-offset` | removed — reported |
+| `--layout-aside-min` | removed — reported |
+| `--layout-column-gap` | removed — reported |
+| `--leading-12` | removed — reported |
+| `--leading-none` | removed — reported |
+| `--leading-normal` | removed — reported |
+| `--leading-relaxed` | removed — reported |
+| `--leading-snug` | removed — reported |
+| `--leading-tight` | removed — reported |
+| `--link-400` | removed — reported |
+| `--link-600` | removed — reported |
+| `--link-color` | `--link` |
+| `--link-underline-offset` | removed — reported |
+| `--mention-available-height` | removed — reported |
+| `--menu-button-h` | removed — reported |
+| `--menu-row-min-h` | removed — reported |
+| `--menu-row-py` | removed — reported |
+| `--muted-20` | removed — reported |
+| `--muted-40` | removed — reported |
+| `--muted-50` | `--muted` |
+| `--muted-60` | removed — reported |
+| `--muted-80` | removed — reported |
+| `--muted-foreground-40` | removed — reported |
+| `--muted-foreground-70` | removed — reported |
+| `--neutral-0` | removed — reported |
+| `--neutral-100` | removed — reported |
+| `--neutral-150` | removed — reported |
+| `--neutral-200` | removed — reported |
+| `--neutral-25` | removed — reported |
+| `--neutral-400` | removed — reported |
+| `--neutral-50` | removed — reported |
+| `--neutral-500` | removed — reported |
+| `--neutral-550` | removed — reported |
+| `--neutral-700` | removed — reported |
+| `--neutral-75` | removed — reported |
+| `--neutral-750` | removed — reported |
+| `--neutral-800` | removed — reported |
+| `--neutral-850` | removed — reported |
+| `--neutral-875` | removed — reported |
+| `--neutral-900` | removed — reported |
+| `--neutral-950` | removed — reported |
+| `--overlay-duration-exit` | removed — reported |
+| `--overlay-edge-full` | removed — reported |
+| `--overlay-edge-inset` | removed — reported |
+| `--overlay-edge-inset-default` | removed — reported |
+| `--overlay-edge-length` | removed — reported |
+| `--overlay-edge-lg` | removed — reported |
+| `--overlay-edge-md` | removed — reported |
+| `--overlay-edge-sm` | removed — reported |
+| `--overlay-enter-scale` | removed — reported |
+| `--overlay-max-width` | removed — reported |
+| `--overlay-region-p` | removed — reported |
+| `--popover-shadow` | `--shadow-lg` |
+| `--primary-10` | removed — reported |
+| `--primary-15` | removed — reported |
+| `--primary-20` | removed — reported |
+| `--primary-25` | removed — reported |
+| `--primary-30` | removed — reported |
+| `--primary-40` | removed — reported |
+| `--primary-5` | removed — reported |
+| `--primary-accent` | `--primary` |
+| `--progress-fill` | removed — reported |
+| `--progress-sweep` | removed — reported |
+| `--pure-black` | removed — reported |
+| `--ref-hue` | removed — reported |
+| `--ref-ink` | removed — reported |
+| `--ref-line` | removed — reported |
+| `--repeater-dragging-opacity` | removed — reported |
+| `--repeater-footer-inset` | removed — reported |
+| `--resource-media` | removed — reported |
+| `--rich-text-block-gap` | removed — reported |
+| `--rich-text-item-gap` | removed — reported |
+| `--rich-text-list-indent` | removed — reported |
+| `--rich-text-quote-indent` | removed — reported |
+| `--row-px` | `--padding-sm` |
+| `--row-py` | `--padding-sm` |
+| `--row-x` | `--padding-sm` |
+| `--row-y` | `--padding-sm` |
+| `--scale` | removed — reported |
+| `--separator-thickness` | removed — reported |
+| `--series-1` | removed — reported |
+| `--series-1-dark` | removed — reported |
+| `--series-2` | removed — reported |
+| `--series-2-dark` | removed — reported |
+| `--series-3` | removed — reported |
+| `--series-3-dark` | removed — reported |
+| `--series-4` | removed — reported |
+| `--series-4-dark` | removed — reported |
+| `--series-5` | removed — reported |
+| `--series-5-dark` | removed — reported |
+| `--shadow-2xl` | `--shadow-lg` |
+| `--shadow-2xs` | `--shadow` |
+| `--shadow-ink` | removed — reported |
+| `--shadow-md` | `--shadow-lg` |
+| `--shadow-sm` | `--shadow` |
+| `--shadow-xl` | `--shadow-lg` |
+| `--shadow-xs` | `--shadow` |
+| `--shell-header-h` | `--header-height` |
+| `--shell-header-height` | `--header-height` |
+| `--sidebar-accent-50` | `--sidebar-accent` |
+| `--sidebar-primary` | removed — reported |
+| `--sidebar-primary-foreground` | removed — reported |
+| `--size-avatar` | removed — reported |
+| `--size-avatar-lg` | removed — reported |
+| `--size-avatar-sm` | removed — reported |
+| `--size-icon` | `--icon-size` |
+| `--size-icon-2xl` | removed — reported |
+| `--size-icon-lg` | removed — reported |
+| `--size-icon-md` | removed — reported |
+| `--size-icon-sm` | `--icon-size-sm` |
+| `--size-icon-xl` | removed — reported |
+| `--size-medallion` | removed — reported |
+| `--slide-nudge` | removed — reported |
+| `--space-2xl` | removed — reported |
+| `--space-2xs` | removed — reported |
+| `--space-lg` | removed — reported |
+| `--space-md` | removed — reported |
+| `--space-sm` | removed — reported |
+| `--space-xl` | removed — reported |
+| `--space-xs` | removed — reported |
+| `--spacing-2xl` | removed — reported |
+| `--spacing-2xs` | removed — reported |
+| `--spacing-lg` | removed — reported |
+| `--spacing-md` | removed — reported |
+| `--spacing-sm` | removed — reported |
+| `--spacing-xl` | removed — reported |
+| `--spacing-xs` | removed — reported |
+| `--sparkline-stroke` | removed — reported |
+| `--success-10` | removed — reported |
+| `--success-30` | removed — reported |
+| `--success-400` | removed — reported |
+| `--success-5` | removed — reported |
+| `--success-600` | removed — reported |
+| `--success-950` | removed — reported |
+| `--surface-px` | `--padding` |
+| `--surface-px-lg` | removed — reported |
+| `--surface-px-xs` | `--padding-sm` |
+| `--surface-py` | `--padding` |
+| `--surface-py-lg` | removed — reported |
+| `--surface-py-xs` | `--padding-sm` |
+| `--surface-x` | `--padding` |
+| `--surface-y` | `--padding` |
+| `--table-head-h` | removed — reported |
+| `--table-selection-w` | removed — reported |
+| `--text-2xl--line-height` | removed — reported |
+| `--text-base--line-height` | removed — reported |
+| `--text-lg--line-height` | removed — reported |
+| `--text-pxs--line-height` | removed — reported |
+| `--text-role-inverse` | removed — reported |
+| `--text-role-main` | `--foreground` |
+| `--text-role-secondary` | `--muted-foreground` |
+| `--text-sm--line-height` | removed — reported |
+| `--text-xl--line-height` | removed — reported |
+| `--text-xs--line-height` | removed — reported |
+| `--tooltip-arrow-size` | removed — reported |
+| `--tracking-tight` | removed — reported |
+| `--tracking-widest` | removed — reported |
+| `--transition-control` | removed — reported |
+| `--violet-500` | removed — reported |
+| `--warning-10` | removed — reported |
+| `--warning-20` | removed — reported |
+| `--warning-30` | removed — reported |
+| `--warning-300` | removed — reported |
+| `--warning-40` | removed — reported |
+| `--warning-500` | removed — reported |
+| `--warning-700` | removed — reported |
+| `--warning-900` | removed — reported |
+| `--warning-950` | removed — reported |
+| `--warning-accent` | removed — reported |
+| `--weight-bold` | removed — reported |
+| `--weight-medium` | removed — reported |
+| `--weight-normal` | removed — reported |
+| `--weight-semibold` | removed — reported |
+| `--white-a10` | removed — reported |
+| `--white-a15` | removed — reported |
+| `--workspace-rail-w` | removed — reported |
+| `--z-raised` | removed — reported |
 
 ## Behaviour changes
 
@@ -726,7 +1248,55 @@ Import the package from ES modules; CommonJS code on Node 20.19 or later can `re
 
 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.
+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. From 3.1, components bring their own CSS, and server rendering with Vite lists the package in `ssr.noExternal`; see docs/learn/migration.md#upgrading-to-31.
+
+### `ThemeSelectors { shared, light, dark, systemLight, systemDark }; createScopedThemeSelectors returning one selector per mode`
+
+**Becomes** `ThemeSelectors { shared }: one block in which each colour is a light-dark() pair` — by hand.
+
+Every colour carries both modes, so a theme needs no mode selectors: the element's color-scheme picks the half, in a dark island inside a light page as well.
+
+Pass `{ shared: selector }` where you passed one selector per mode. Re-export a stylesheet written by an earlier ThemeTweaker: it names variables the theme no longer declares.
+
+### `themeToStyle(theme, mode)`
+
+**Becomes** `themeToStyle(theme)` — by hand.
+
+The style carries both halves of each colour, and the element's color-scheme picks one.
+
+Drop the second argument.
+
+### `ThemeTweakerSection inverse-surfaces, global-scales, actions-controls, rows-surfaces, media, content-widths and adaptive-layout, and the matching keys of ThemeTweakerStrings.sections`
+
+**Becomes** `ThemeTweakerSection tints, spacing, controls and motion` — by hand.
+
+The default fields are the theme's own variables, and the sections follow them.
+
+In custom `fields`, put spacing under `spacing`, control and icon sizes under `controls`, durations under `motion`, and the tint strengths under `tints`. A complete `strings.sections` names the new sections.
+
+### `deriveThemeTypeScale writing --text-*--line-height; deriveThemeElevation writing --shadow-2xs to --shadow-2xl; deriveThemePalette writing --link-color and --sidebar-primary`
+
+**Becomes** `the type steps; --shadow and --shadow-lg; --link` — by hand.
+
+The recipes write the theme's variables. Text pairs each type step with its own line height, and elevation has two steps: raised and floating.
+
+Nothing to change where you apply a recipe's result. If you read its keys, read the new names.
+
+### `Tone unions spelled out per component: VendorStat.changeTone, AlertTone, ProgressTone, IconBadgeTone, BadgeTone`
+
+**Becomes** `the same members, written as SemanticTone or an Extract of it` — a direct rename, by hand.
+
+Every tone prop takes a subset of one union, so a tone added to the kit reaches every component that takes it.
+
+Nothing to change: each component accepts the same values.
+
+### `Each module's stylesheet, or `style.css`, imported beside the JavaScript`
+
+**Becomes** `Components that bring their own CSS` — by hand.
+
+Each module stylesheet imported from JavaScript carried its own copy of `core.css`, and a package built on this one could not reference them from a stylesheet. Tying the CSS to the JavaScript module graph uses what the bundler already knows: a module that is used brings its CSS, once; a module that is not brings none.
+
+In a bundled app, import components only: the codemod removes JavaScript imports of `themelia-ui/style.css` and module stylesheets, and lists `@import`s of kit stylesheets to remove from CSS the app bundles, a Tailwind entry included. Server rendering with Vite lists `themelia-ui` in `ssr.noExternal`. Pages with no bundler link `style.css`.
 
 ## Data files and the component finder