themelia-ui 3.0.0 → 3.1.0

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

@@ -3,6 +3,134 @@
 What changes between versions, what to do when you upgrade, and which changes a stable major
 allows.
 
+## Upgrading to 3.1
+
+3.1 renames and removes public API as well as adding to it. Upgrade deliberately, not
+through a caret range: pin `themelia-ui` to `~3.0.0` until you have run the codemod and fixed
+what TypeScript reports.
+
+**Blocks are published under `blocks/`.** The tier the documentation, the component index
+and the finder call Blocks now has subpaths that say so:
+
+| was | is |
+| --- | --- |
+| `themelia-ui/patterns/analytics` | `themelia-ui/blocks/analytics` |
+| `themelia-ui/patterns/onboarding` | `themelia-ui/blocks/onboarding` |
+| `themelia-ui/patterns/timelines` | `themelia-ui/blocks/timelines` |
+| `themelia-ui/admin/patterns/access` | `themelia-ui/blocks/admin/access` |
+| `themelia-ui/admin/patterns/commerce` | `themelia-ui/blocks/admin/commerce` |
+
+Module stylesheet subpaths are removed. Importing a component in a bundled app brings its CSS.
+
+**Components bring their own CSS.** In a bundled app, importing a component now brings its
+stylesheet, once, and a module you never import brings none. To upgrade:
+
+1. Run the codemod over each directory that holds application code: `src/`, and `app/` or
+   `.storybook/` where you have them.
+   It removes JavaScript imports of `themelia-ui/style.css` and of module stylesheets, which would
+   now load the CSS twice.
+2. The codemod removes obsolete module CSS `@import`s. Review any remaining stylesheet
+   references it reports. With Tailwind, keep `@import "tailwindcss"` and the bridge, and drop
+   `@import "themelia-ui/style.css"` or `@import "themelia-ui/core.css"` from the Tailwind entry.
+3. If the application renders on the server with Vite (Astro, React Router, TanStack Start, Vike),
+   list `themelia-ui`, and any installed package that imports it, in `ssr.noExternal`; Astro
+   renders the kit unstyled without it. See
+   [Server rendering with Vite](installation.md#server-rendering-with-vite).
+4. If your bundler config sets its own resolve conditions, keep `module` in them.
+5. Pages that link stylesheets without a bundler link `style.css`.
+
+**Fill style is `appearance`.** `tone` is colour, `appearance` is fill and `variant` is
+structure, on every component. TypeScript reports each rename:
+
+| was | is |
+| --- | --- |
+| `buttonStyle` on a Button, a Button-like component or an action definition | `appearance` |
+| `ButtonStyle`, `ActionButtonStyle` | `ButtonAppearance`, `ActionAppearance` |
+| `defaults: { button: { buttonStyle } }` | `defaults: { button: { appearance } }` |
+| `variant` on `Badge`, `Toggle` and `SidebarMenuButton` | `appearance` |
+| `BadgeVariant` | `BadgeAppearance` |
+| `badgeVariants({ tone, variant })` on your own element | `<Badge tone appearance render={<a … />}>` |
+| `badgeVariant` on a metadata badge value | `badgeAppearance` |
+| `confirmStyle` on an overlay or an action modality | `confirmAppearance` |
+
+Button renders `data-appearance` instead of `data-style`, and Toggle `data-appearance`
+instead of `data-variant`: update CSS that selects either.
+
+**Two steps for every size.** A size, padding or gap prop offers `default` and `sm`. `md` is
+`default`, which is also what leaving the prop out gives you; a step larger than the default
+is gone. The gaps map like this:
+
+| was | is |
+| --- | --- |
+| `gap="2xs"`, `"xs"`, `"sm"`, `"md"` | `gap="sm"` (8px) |
+| `gap="lg"`, `"xl"`, `"2xl"` | `gap="default"` (16px), or no `gap` |
+| no `gap` on a `Stack` or `Split` (8px) | 16px; write `gap="sm"` to keep 8px |
+
+Widths take `default`, `sm`, `full`, `none` or a CSS length such as `"48rem"`, and a free
+string no longer type-checks. `Slider` and `SliderField` lose `size`, `InputGroupButton`
+takes `iconOnly` instead of its icon sizes, and an action modality's `size`, which nothing
+read, is gone.
+
+**`density` belongs to the provider.** `MetadataList density="compact"` becomes
+`size="sm"`, `MediaLibrary density="compact"` becomes `size="sm"`, `ActivityFeed density`
+becomes `variant`, and `AiTask density="expanded"` becomes `defaultExpanded`. CSS that
+selects `[data-row-density]`, `[data-media-density]` or `[data-activity-density]` selects
+`[data-size]` or `[data-variant]`.
+
+`Text` drops `size="xxs"` and `weight="regular"`: write `xs` and `normal`.
+
+**The theme is one level.** It is about eighty variables, declared once at `:root`, each
+colour a `light-dark(light, dark)` pair. For a theme of your own:
+
+- Declare it on `:root` alone. The selector list 3.0 asked for (`:root, [data-ui-scope],
+  [data-density], [data-theme], .light, .dark`) is not needed: nothing below `:root` declares a
+  theme variable again.
+- Write a dark value into the colour's pair, `--primary: light-dark(#2563eb, #60a5fa)`, rather
+  than a `.dark { … }` block, which colours a dark page but misses a dark region inside a light
+  one.
+- The palette, the alpha steps, the spacing ladder, the control, icon and avatar ladders, the
+  derived role variables and the scale factors are gone. The codemod renames a variable that
+  has a successor and reports the rest:
+
+| was | is |
+| --- | --- |
+| `--space-2xs` to `--space-md` | `--gap-sm` between things, `--padding-sm` for an inset |
+| `--space-lg` to `--space-2xl` | `--gap` between things, `--padding` for an inset |
+| `--surface-px`, `--surface-py`; `--row-px`, `--row-py` | `--padding`; `--padding-sm` |
+| `--control-h`, `--control-h-sm` | `--control-height`, `--control-height-sm` |
+| `--size-icon`, `--size-icon-sm` | `--icon-size`, `--icon-size-sm` |
+| `--primary-10` and every other alpha step | `color-mix(in oklab, var(--primary) var(--tint), transparent)`; a line takes `--tint-strong` |
+| `--accent-50`, `--border-60`, `--muted-50` | `--accent`, `--border`, `--muted` |
+| `--control-border`, `--focus-ring-color`, `--link-color` | `--input`, `--ring`, `--link` |
+| `--shadow-xs`, `--shadow-sm`; `--shadow-md` to `--shadow-2xl`, `--popover-shadow` | `--shadow`; `--shadow-lg` |
+| `--duration-normal`, `--duration-instant`, `--ease-out` | `--duration`, `--duration-fast`, `--ease` |
+| `--leading-*`, `--weight-*`, `--tracking-*` | Text's `lineHeight`, `weight` and `caps` |
+| `--scale`, `--density-scale` | the provider's `scale` and `density` |
+| `--inverse-*` | a nested provider with `colorScheme: "dark"` |
+| `--animate-spin` and the other `--animate-*` | `--keyframes-spin` and the others, which hold the name alone: `animation: var(--keyframes-spin) 1s linear infinite` |
+
+`--text-scale` stays, and Text multiplies each step by it. A component variable you set from
+outside, such as `--content-block-p`, `--overlay-region-p`, `--field-label-width` or
+`--chart-aspect`, is the component's own now: set the theme variable it reads, or style the
+component through `className`. With Tailwind, `p-padding` and `gap-gap-sm` replace `p-md` and
+the other spacing keys, and `rounded` is the container radius.
+
+**A browser floor for `light-dark()`.** Safari 17.5 or newer; Chrome and Edge 125 and Firefox
+121 are unchanged.
+
+Run the codemod from your project over each directory that holds application code, dry
+first; the commands below show `src/`. It rewrites the moved subpaths, removes the
+stylesheet imports components now bring, renames each theme variable that has a successor,
+and reports the rest:
+
+```sh
+node node_modules/themelia-ui/scripts/consumer/codemod.mjs --dry-run src/
+node node_modules/themelia-ui/scripts/consumer/codemod.mjs src/
+```
+
+Every change with its replacement is listed in the
+migration reference (`node_modules/themelia-ui/docs/generated/migration.md`).
+
 ## Upgrading to 3.0
 
 3.0 changes how the package loads, and gives a few props one shape.
@@ -16,6 +144,9 @@ the package as it is. Server rendering and test runners need no configuration fo
 CommonJS code on Node 20.19 or later can `require()` it. Jest still needs the package
 exempted in `transformIgnorePatterns`.
 
+From 3.1, components bring their own CSS again, and server rendering with Vite lists the
+package in `ssr.noExternal`; see [Upgrading to 3.1](#upgrading-to-31).
+
 TypeScript flags the rest:
 
 - `Scope` takes `render` instead of `as`: `<Scope vars={vars} render={<section />}>`.
@@ -201,14 +332,14 @@ Every change is one of:
 - **additive**: a new export, a new optional prop
 - **documentation-only**: no runtime or type change
 - **behaviour-preserving internal**: a refactor whose observable behaviour is identical
-- **deprecation**: the old name still works, and says what replaces it
+- **deprecation**: an old name still works while a replacement is available
 - **breaking**: anything else
 
-## Within a stable major
+## Upgrade policy
 
-An alias introduced during a stable major is deprecated in that major, documented with its
-replacement, and removed only in the next one. It stays for one full stable major unless
-security or correctness makes keeping it unsafe.
+3.1 removes obsolete aliases and adapters without retaining them for another release. Pin the
+installed version until the application is ready to apply the migration guide, type-check and
+build. Breaking changes are recorded before the API snapshot is updated.
 
 ## Import paths
 

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

@@ -65,37 +65,31 @@ below a slice as well as at it:
 </UIProvider>
 ```
 
-This applies to every record-shaped field: `theme.colors`, `theme.palette`, `theme.vars`,
-`typography.fonts`, `typography.sizes` and `motion.durations`. Below them a record is a flat
-map of token to value, and a value is replaced, not merged.
+This applies to every record-shaped field: `theme.colors`, `theme.vars`, `typography.fonts`,
+`typography.sizes` and `motion.durations`. Below them a record is a flat map of variable to
+value, and a value is replaced, not merged.
 
 That is the configuration components read, and the CSS follows it: each scope writes the
 merged overrides on its element, so inside the nested scope above `--primary` is red and
-`--secondary` is green. Raw inputs (palette steps, radii, fonts, durations and the scale
-factors) inherit through every boundary. Semantic colours and type sizes do not: a `Scope`,
-or any other element on the boundary list, declares them again from the palette. To keep a
-colour across one of those, set it through `theme.palette` or declare it at the boundary
-list; see [Theming](theming.md#setting-a-theme).
+`--secondary` is green. Nothing below `:root` declares a theme variable again, so every value
+inherits through any element, a `Scope` or a `data-density` region included; see
+[Theming](theming.md#setting-a-theme).
 
 ## Scope — tokens only
 
-Overriding a factor requires a **scope boundary**, not just any element:
+`Scope` sets theme variables on a region, without the config machinery:
 
 ```tsx fragment — shape only, not a program
-<Scope vars={{ "--density-scale": 0.8 }}>
+<Scope vars={{ "--control-height": "2.5rem" }}>
   <Toolbar />
 </Scope>
 ```
 
 `Scope` renders a `div` without layout. `render` picks another element, as on every
-component (`render={<section />}`), and `transparent={false}` gives it a box.
-
-Derived tokens are declared at `:root, [data-ui-scope], [data-density], [data-theme], .light,
-.dark` (see `src/styles/SCOPES.md` (`node_modules/themelia-ui/src/styles/SCOPES.md`)). A plain
-`<div style={{ "--density-scale": 0.8 }}>` sets the variable and nothing reads it: the
-measurements above it already resolved against the old value. `Scope` renders
-`data-ui-scope`, which puts the element on that list and makes every derived token
-re-compute.
+component (`render={<section />}`), and `transparent={false}` gives it a box. Every
+component inside reads the variables it sets, because components compute from the theme where
+they use it; any element with a `style` does the same, and `Scope` only adds the missing
+layout rule and the `data-ui-scope` marker.
 
 ## Portals and scopes
 
@@ -175,7 +169,7 @@ ship the scrollbar rule in the consuming application's stylesheet:
 ```
 
 `disableStyleElements` does not disable kit behavior; it moves those small rules into the
-consuming app. It does not replace the normal `core.css`, module stylesheet, or `style.css` import.
+consuming app. It does not change how the kit's CSS loads.
 
 ## Reading the config