themelia-ui 3.0.0 → 3.2.0

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

@@ -32,8 +32,9 @@ test("global search returns focus after dismissal", async ({ page }) => {
 Prefer role- and name-based assertions over CSS Module selectors. When a visual or state
 assertion needs a DOM hook, use `data-slot`, documented BEM hooks, or the state attributes
 the primitives set (`data-open`, `data-checked`, `data-disabled`, `data-highlighted`,
-`data-popup-open`). These are Base UI's attributes, not Radix's: `[data-state="open"]`
-matches nothing.
+`data-popup-open`). Use Base UI's documented attributes for its primitive states rather
+than assuming Radix's `[data-state="open"]`. Some kit modules expose their own `data-state`
+contract; use it only where the selected API documents it.
 
 ## Theme contract check
 
@@ -41,11 +42,65 @@ Create one application fixture that changes primary colour, surface/background r
 radius, density, and typography scale at a scope boundary. If a component ignores it, report
 the module and token before adding a local patch: the package may be missing a derivation.
 
+## Offline diagnosis and skill freshness
+
+Run the commands from the package installed in this application:
+
+```bash
+node node_modules/themelia-ui/scripts/consumer/install-skill.mjs --project=. --check --json
+node node_modules/themelia-ui/scripts/consumer/diagnose.mjs --project=. --json src/
+```
+
+Both checks are read-only. Diagnostics use the consumer's installed TypeScript parser and
+the package's generated export/migration facts. Supply explicit paths. Unsupported formats,
+parse failures, missing paths, metadata or parser produce exit 2 (incomplete); definite
+contract errors produce exit 1; complete checks without errors produce exit 0. Advisory
+composition/private-style warnings do not establish a defect. Excluded build/dependency
+directories and symlinks are not followed. Reports name the checked and skipped rules/files.
+
+Freshness reports expected and installed versions plus missing, stale, modified or unmanaged
+copies. Review modifications before reinstalling a generated copy. The installer refuses local edits
+until `--overwrite-modified` explicitly replaces reviewed generated content. Keep application policy
+in a separate skill; an unmanaged same-name skill is preserved. Missing metadata requires
+repairing the package installation or consulting the matching release, never inventing an API.
+
+If an installed copy's manifest is missing or invalid, the installer repairs it automatically
+only when its remaining files match the packaged content. Differing or extra files require
+review and `--overwrite-modified`, just like edits to a copy with a valid manifest.
+
+Replacements are staged before writes, and caught write failures restore backups. An abrupt
+process termination can leave mixed versions across targets and sibling `.backup-*` or
+`.installing-*` directories. Run `--check`, review those retained directories, preserve any
+local policy, and reinstall the intended generated copies. A backup-cleanup error means the
+new copies were installed; the error names the retained backup for review and manual cleanup.
+
+The browser observer (`node_modules/themelia-ui/docs/build/browser-composition-fixture.ts`) accepts an already open caller
+fixture and observes overflow, repeated sibling headings and control visibility. It performs
+no navigation, click or submission. These geometry/semantic observations are advisory; they
+do not establish accessibility or business acceptance. Optional browser tooling belongs in
+the application's test dependencies, not the UI runtime.
+
+Opt into interaction tests only against explicit mock actions. The [complete workflows](reference-workflows.md)
+provide scoped late responses, pending/empty/error lists, nested cancel, resolved validation,
+workspace selection and retained locale drafts. Assert keyboard selection without accidental
+form submission, one Escape layer at a time, focus return, associated errors and explicit
+successful completion. Do not crawl unknown application routes or submit business forms.
+
+## Completion record
+
+Record installed package/skill versions; selected owners and seams; shared callers inspected;
+fixture routes and states; viewport widths; themes, densities and locales; keyboard/focus
+interactions; commands and observed results. Separate type/build evidence, behavior tests,
+visual inspection and application acceptance. Name unavailable conditions explicitly.
+
+When no browser is available, report types/build/static findings and mark interaction and
+visual checks unverified. Passing named static/browser checks does not establish permissions,
+data integrity, persistence, backend sanitization or every product workflow.
+
 ## Upgrade check
 
 Read the changelog (`node_modules/themelia-ui/CHANGELOG.md`), run the package's codemod when a release names one
 (`node node_modules/themelia-ui/scripts/consumer/codemod.mjs --dry-run src/`), and let the
-application's own type-check compare the installed declarations. Within a major, a removal
-keeps a deprecated alias until the next major unless keeping it would be unsafe or
-incorrect; a major may remove names outright, and its migration guide lists each one. See
+application's own type-check compare the installed declarations. Removed names have no
+compatibility alias in 3.1; its migration guide lists each replacement. See
 [API compatibility](api-compatibility.md).

package/CHANGELOG.md

@@ -1,5 +1,217 @@
 # Changelog
 
+## 3.2.0 — 2026-10-04
+
+- Skill installation preserves edits when installed metadata is missing and keeps installed
+  copies intact if backup cleanup fails. Diagnostics check namespace accesses, escaped CSS
+  imports and private variables from core styles.
+- Nested action success closes both layers; nested-action and media references use packaged
+  triggers to restore focus in Safari. Escape leaves a modal child in control when its parent
+  is nonmodal. Scope changes abort old lookups before committed layout callbacks.
+- The media-picking reference commits replacement ids only after explicit confirmation.
+- Responsive GridCell spans support `full` at individual breakpoints and restore numeric spans.
+- Consumer guides cover structural owners, spacing, responsive widths and subject blocks;
+  framework guidance distinguishes ordinary SSR from React Server Components boundaries.
+- Mobile workspace disclosure keeps navigation open until a same-app destination is selected.
+- ResourceCombobox, SuggestionsCombobox and useSuggestions accept `scopeKey` to invalidate
+  asynchronous lookups while retaining controlled selection and query state.
+- Open combobox lists guard Enter during loading, empty results and IME composition;
+  nested native dialogs preserve their parent's draft and focus on child dismissal.
+- Nine complete public-API reference workflows cover record details, server collections,
+  forms, scoped lookups, nested actions, navigation, media, communications and rich content.
+- Context-aware discovery, ownership guides and the generated consumer skill share those
+  sources. Skill checks report version and content drift; reinstalling local edits requires
+  explicit `--overwrite-modified`.
+- The packaged read-only diagnostic command checks imports and stylesheet contracts,
+  reports conservative composition warnings and identifies incomplete analysis.
+
+## 3.1.0 — 2026-09-28
+
+This release renames and removes public API. Read
+[Upgrading to 3.1](docs/learn/migration.md#upgrading-to-31) before you upgrade, then run the
+packaged codemod from your project, dry first:
+
+```sh
+node node_modules/themelia-ui/scripts/consumer/codemod.mjs --dry-run src/
+```
+
+### Breaking
+
+- Blocks are published under `themelia-ui/blocks/`, the name the documentation, the
+  component index and the finder already use. `themelia-ui/patterns/analytics`,
+  `onboarding` and `timelines` are now `themelia-ui/blocks/analytics`, `onboarding` and
+  `timelines`; `themelia-ui/admin/patterns/access` and `commerce` are
+  `themelia-ui/blocks/admin/access` and `commerce`. The codemod rewrites JavaScript imports.
+- Per-module CSS subpaths are removed. Component imports bring their stylesheets in bundled
+  apps; direct stylesheet links use `themelia-ui/style.css`.
+- `ColorInputProps.emitHex` is removed; use `format="hex"`. The
+  `createExecCommandEngine` adapter is removed; RichTextEditor uses TipTap by default and
+  `createTiptapEngine` remains available for custom schemas.
+- Complete `AnalyticsStrings`, `AsyncComboboxStrings` and `MediaLibraryStrings` translations
+  must provide all declared keys. `MediaLibraryState` requires its recovery and visible-selection
+  controls; `useMediaLibrary` supplies them.
+- The theme is one level: about eighty variables declared once at `:root`, each colour a
+  `light-dark(light, dark)` pair, and every length, shadow, tint and duration in twos.
+  Components compute everything else where they use it, so a value set anywhere reaches every
+  component below it, and a dark region inside a light page needs no second set of values.
+  - The palette, the alpha steps (`--primary-10`), the spacing ladder (`--space-*`), the
+    control, icon and avatar ladders, the derived role variables, the dark twins, the
+    `--scale` and `--density-scale` factors, and `--font-serif`, which nothing read, are gone. The codemod renames each variable that
+    has a successor (`--control-h` to `--control-height`, `--size-icon` to `--icon-size`,
+    `--link-color` to `--link`) and reports the rest.
+  - A theme of your own is one `:root` block; the selector list for re-declaring colours at
+    every boundary is not needed.
+  - The `theming` cascade layer is gone: the order is `tokens, base, components, utilities`.
+  - `--animate-*` are gone. A `--keyframes-*` variable holds a keyframes name and you state
+    the timing: `animation: var(--keyframes-spin) 1s linear infinite`. The kit's keyframes
+    are named `themelia-*`, so a bare `spin` or `pulse` is no longer the kit's.
+  - `tokens.json` has no palette group; each colour is a token per mode, and shadows,
+    durations, the easing curve and the font stacks carry their DTCG types.
+  - Safari 17.5 or newer is required, for `light-dark()`.
+- Fill style is `appearance` on every component that has one, so `tone` is colour,
+  `appearance` is fill and `variant` is structure:
+  - `buttonStyle` becomes `appearance` on `Button`, `TextButton`, `LoaderButton`,
+    `TooltipButton`, every component that forwards Button props, and action definitions.
+    `ButtonStyle` and `ActionButtonStyle` become `ButtonAppearance` and `ActionAppearance`,
+    provider defaults read `defaults.button.appearance`, and Button renders
+    `data-appearance` instead of `data-style`.
+  - `Badge`'s `variant` becomes `appearance` (`BadgeAppearance`); a metadata badge value's
+    `badgeVariant` becomes `badgeAppearance`. `badgeVariants` is no longer exported: a badge
+    takes its colour from its tone, so render a `Badge` (with `render` for a link) instead.
+  - `Toggle`'s and `SidebarMenuButton`'s `variant` become `appearance`; Toggle renders
+    `data-appearance` instead of `data-variant`.
+  - The overlays' and action modalities' `confirmStyle` becomes `confirmAppearance`
+    (`OverlayButtonAppearance`).
+- Every size, padding and gap prop has two steps, `default` and `sm`:
+  - `gap`, `rowGap`, `columnGap` and `amount` on `Stack`, `Grid`, `AdaptiveGrid`, `Split` and
+    `Bleed` take `none`, `sm` (8px) or `default` (16px), and an unset `Stack` or `Split` gap
+    is now 16px instead of 8px.
+  - `maxWidth` and `sideWidth` take `default` (the content width), `sm`, `full`, `none` or a
+    CSS length; `AdaptiveGrid`'s `minColumnWidth` takes `default`, `sm` or a length. A free
+    string is no longer accepted, so a misspelt step cannot pass as a length.
+  - `ComponentScale` is `default | sm`: `Spinner`'s `size`, `Empty`'s and
+    `ResourceDetailsSection`'s `padding` and `DataTable`'s `size`. `md` is `default`; `lg` is
+    gone.
+  - `Avatar`, `SidebarMenuButton` and `AuthShell` lose `size="lg"`; `SidebarMenuButton`,
+    `SidebarMenuSubButton` and `AuthShell` name their middle step `default`.
+  - An overlay's, `SheetContent`'s and `ActionSheet`'s `size` takes `default`, `sm`, `full`
+    or a CSS length, and `length` and `inset` take a CSS length.
+  - `Slider` and `SliderField` have no `size`: under a finger the track and thumb grow into
+    a larger target by themselves. `InputGroupButton` has one size, and `iconOnly` makes it
+    square.
+  - `ActivityFeed`'s `itemSpacing` is `default | sm`.
+- `density` belongs to the provider. `MetadataList`'s becomes `size` (`default | sm`, and
+  `data-size`), `MediaLibrary`'s and its parts' become `size`, `ActivityFeed`'s and its
+  rows' become `variant` (`data-variant`), and `AiTask`'s becomes `defaultExpanded`.
+- An action modality's `size` and the `ActionOverlaySize` type are gone: nothing read them.
+- `Text` drops `size="xxs"` and `weight="regular"`; write `xs` and `normal`.
+- The ThemeTweaker writes one block in which each colour is a `light-dark()` pair, so an
+  exported theme follows `color-scheme` wherever it is applied:
+  - `ThemeSelectors` is `{ shared }`, and `createScopedThemeSelectors` returns it; the `light`
+    and `dark` selectors are gone.
+  - `themeToStyle(theme)` takes no mode: the style carries both halves.
+  - The default fields are the theme's variables, grouped into new `ThemeTweakerSection`s.
+- The theming recipes write the theme's variables: `deriveThemePalette` sets `--link` and no
+  sidebar primary, `deriveThemeTypeScale` writes the type steps (Text pairs each step with its
+  line height), and `deriveThemeElevation` writes `--shadow` and `--shadow-lg`.
+- The provider's `theme.colors` takes the theme's 38 colours (`SemanticToken`). `link-color`
+  is `link`, and `overlay-backdrop` is new. The `inverse-*` colours, `primary-accent`,
+  `destructive-accent`, `warning-accent` and `sidebar-primary*` are gone: an inverse region
+  is a nested provider with its own `colorScheme`, and a tone's text colour comes from its
+  tone. `theme.palette` and the `PaletteToken` type are gone with the palette.
+- `MotionConfig.durations` takes `fast` and `normal`; `instant` is gone.
+- The Tailwind bridge follows the theme. `p-padding`, `p-padding-sm`, `gap-gap` and
+  `gap-gap-sm` replace the spacing keys (`p-md` and the rest), `rounded` is the container
+  radius, and `animate-*`, `leading-*`, `tracking-*` and the shadow steps other than
+  `shadow` and `shadow-lg` are Tailwind's own again.
+- Components bring their own CSS in a bundled app: importing a component from its subpath
+  adds its stylesheet, once, with one copy of `core.css`, and a module the application never
+  imports adds none. Remove JavaScript imports of `style.css` and of module stylesheets, which
+  now load the CSS twice; the codemod does it. Server rendering with Vite (Astro, React
+  Router, TanStack Start, Vike) needs the package in `ssr.noExternal`. 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. Pages with no bundler link
+  `style.css`. See [Upgrading to 3.1](docs/learn/migration.md#upgrading-to-31).
+
+### Added
+
+- Four ready-made themes in `themelia-ui/theming`, each a style rather than a colour: Soft,
+  Sharp, Dense and Editorial. A theme is a `ThemePreset` (a label, a description and the
+  provider config it sets), so it reaches past colour to radii, shadows, density, type, motion
+  and component defaults such as the card surface. Every theme's colours hold WCAG AA contrast
+  in both modes. The theme editor's `themeFromConfig()` loads a theme's colours and variables to
+  edit and export. The documentation site gains a Themes page and a Theme menu in its header.
+- `Text` takes `heading`, the heading face (`--font-heading`) for a title that is not a
+  document heading. Card and dialog titles use it, so a theme's heading font reaches them.
+- `DataTable` rows expand. `expandedRow` turns on a toggle at each row's start and the panel it
+  opens under the row: `render` draws the panel, and `onLoad` optionally fetches what it shows
+  when the row opens, with a skeleton meanwhile, the request aborted when the row closes, Retry
+  on failure and the result kept for the next open. `canExpand` leaves a row without a toggle,
+  `multiple: false` keeps one row open at a time, and `expanded`, `defaultExpanded` and
+  `onExpandedChange` control the open rows. The panel lines up with the first column, stays in
+  view on a table scrolled sideways, and keeps a panel that throws or suspends inside its row.
+- `textClassName()` lends Text's classes to an element Text cannot wrap: a native control,
+  a button's label, a table cell. `Text` takes `mono` and `caps`.
+- `AiShimmer` takes `size`, a step on the type scale as on `Text`.
+- `richTextClassName()` lends RichText's prose surface to an element RichText cannot render,
+  such as an editor's content-editable root.
+- Each block's page shows it composed from the lower tiers (analytics, timelines, onboarding,
+  access and commerce), for the case configuration does not reach.
+
+### Changed
+
+- `package.json` publishes modules through tier subpath patterns such as `./base/*`.
+- Destructive is lighter in dark mode, so red text holds 4.5:1 on the hover fill, on its own
+  tint in a popover, and as a soft badge in a selected row.
+- A framed Card's band is the item inset, and the surface inside it takes the concentric
+  corner, so a square-cornered theme keeps the band.
+- `MetricTrendChip` and `MetricComparison` render `data-tone` as `success`, `destructive` or
+  `neutral`, the kit's tone names, instead of `positive` and `negative`.
+- Checkboxes, radios and switches keep one size, 1.125rem, at every density.
+- A disabled control shows the not-allowed cursor and dims; it no longer ignores the pointer.
+- Menus take the radius of the control they open from: DropdownMenu, ContextMenu, ActionMenu,
+  Menubar, Select, Combobox, PopoverMenu, NavigationMenu and a Command inside a popover draw
+  `--radius-sm`, with rows at half of it inset by the other half, so the corners still nest.
+  Content popovers, hover cards and dialogs keep the container radius.
+- Table headers are quieter: labels in the muted colour, with the sorted column's in the body
+  colour, a lighter band on `DataTable`, and 42px instead of 48px, following density. The whole
+  head cell sorts, and an unsorted column's arrow shows on hover or keyboard focus; touch
+  screens keep a faint one. `TableSkeleton` reserves the new height.
+- A component used inside another, such as a Button in a menu, looks the same whatever order
+  a bundler emits the CSS in, and the same with `style.css` as in a bundled app.
+
+### Fixed
+
+- `MonoValue` renders in the monospaced face its documentation promises.
+- `MapTooltip` draws its own surface; Leaflet's stylesheet left bare text on the map, and
+  its arrow points at the marker on every side.
+- The fade at a scroll edge of `Carousel` and a scrolling `Table` lifts while the region
+  has focus, so it no longer hides the focus outline.
+- `ResizableHandle` shows its active state while dragged again.
+- A vertical `Slider` has its 10rem track; the track collapsed.
+- Text in an `InputGroup` textarea is inset from the frame.
+- A `Card` title with an info button lines up with one without.
+- A default `Sheet` is 384px wide again; it rendered at 472px.
+- Upload file sizes render at the small secondary size.
+- A permission a role lacks, and a refund stage not yet reached, recede again.
+- The AI composer draws one frame; it drew the field's frame inside its own.
+- The breadcrumb bar no longer clips the sidebar trigger's focus outline, and the collapsed
+  sidebar rail no longer shows a sliver of each row's label.
+- A nested provider with `density="default"` resets a density set further out; it kept the
+  outer one.
+- A nested provider that sets `density` under a scaled one sizes that density at the
+  inherited scale; the outer lengths outranked the preset.
+- Map controls sit on a ground and an edge of their own; over the tiles they were
+  see-through. An active drawing tool keeps its fill.
+- A scrolling `DataTable`'s focus outline runs round the whole frame; its sticky header and
+  pinned columns painted over it.
+- A failed attachment keeps its file name in view: the error shares the row, may widen the
+  chip to the tray, and shows in full on hover. Each attachment's link is named by its file;
+  every one was named "Download".
+- The kit's animations run on a page that also loads Tailwind or tw-animate-css. Their
+  `spin`, `pulse`, `enter` and `exit` replaced the kit's keyframes, or the kit's replaced
+  theirs, whichever loaded last.
+
 ## 3.0.0 — 2026-09-27
 
 A major release. The package is ES modules whose JavaScript imports no CSS, so each module's

package/README.md

@@ -14,7 +14,7 @@ themed through one set of CSS variables.
   plugin is needed; applications that use Tailwind CSS v4 get a bridge to the theme.
 - **Overrides without `!important`.** Component rules live in cascade layers, so a utility
   in `className` or ordinary application CSS wins.
-- **Import only what you use.** Every module has its own JavaScript and CSS subpath.
+- **Import only what you use.** Every module has its own subpath and brings only its own CSS.
   Optional peers such as charts, maps and rich text are needed only by the modules that use
   them.
 - **Your application keeps its policy.** Routing, data fetching, persistence, permissions and
@@ -43,18 +43,17 @@ npm install themelia-ui
 React 19 and `react-dom` are required peers. Every other peer is optional and needed only by
 the modules that use it; the [import table](https://unpkg.com/themelia-ui/docs/generated/imports.md) lists which.
 
-Themelia supports Chrome and Edge 125, Firefox 121 and Safari 16.4 or newer. Builds and
+Themelia supports Chrome and Edge 125, Firefox 121 and Safari 17.5 or newer. Builds and
 server rendering need Node 20.19 or newer.
 
 ## Quick start
 
-Put `UIProvider` at the root of the application, import the stylesheet once, and import
-each component from its module's subpath:
+Put `UIProvider` at the root of the application and import each component from its module's
+subpath. In a bundled app, a component brings its own CSS:
 
 ```tsx
 import { Button } from "themelia-ui/base/buttons"
 import { UIProvider } from "themelia-ui/ui-provider"
-import "themelia-ui/style.css"
 
 export function App() {
   return (
@@ -65,7 +64,7 @@ export function App() {
 }
 ```
 
-`style.css` holds the CSS of the whole library. To load only what the application uses, see
+Server rendering with Vite and pages with no bundler need one step more; see
 [Load the CSS](#load-the-css).
 
 ## Load the CSS
@@ -73,42 +72,35 @@ export function App() {
 The styles are precompiled CSS in cascade layers, declared in this order:
 
 ```css
-@layer tokens, theming, base, components, utilities;
+@layer tokens, base, components, utilities;
 ```
 
-Three kinds of stylesheet are published:
+**In a bundled app**, importing a component brings its stylesheet, once, and a module the
+application never imports brings none. Do not also import `style.css` or a module stylesheet
+from JavaScript; that loads the rules twice.
 
-| Import | Contains |
-| --- | --- |
-| `themelia-ui/style.css` | Everything: `core.css` and the rules of every module. |
-| `themelia-ui/<module>.css`, such as `themelia-ui/base/buttons.css` | One module's rules and the stylesheets they build on. It imports `core.css` itself. |
-| `themelia-ui/core.css` | The theme variables, the layer order, the Geist typefaces and the base element styles. No component rules. |
-
-A module whose components draw nothing has no stylesheet. The
-[import table](https://unpkg.com/themelia-ui/docs/generated/imports.md) lists the JavaScript and CSS path of every module.
+**Server rendering with Vite** (Astro, React Router, TanStack Start, Vike) lists the package
+in `ssr.noExternal`, or Vite hands it to Node without its CSS:
 
-### Import the stylesheets
-
-The JavaScript imports no CSS. Import `style.css` once, or each module's stylesheet beside its
-import; a bundler that handles CSS imports, such as Vite, webpack or Rspack, includes each file
-once however many modules import it:
-
-```tsx
-import { Button } from "themelia-ui/base/buttons"
-import "themelia-ui/base/buttons.css"
-import { Page } from "themelia-ui/layout/page"
-import "themelia-ui/layout/page.css"
+```ts
+// vite.config.ts, or the vite key of astro.config.mjs
+export default { ssr: { noExternal: ["themelia-ui"] } }
 ```
 
-A component whose stylesheet is not imported renders unstyled. Import `core.css` on its own
-only when your own CSS needs the theme variables before any module stylesheet loads.
+**Without a bundler**, link `themelia-ui/style.css`; it includes `core.css`:
+
+| Stylesheet | Contains |
+| --- | --- |
+| `themelia-ui/core.css` | The theme variables, the layer order, the Geist typefaces and the base element styles. No component rules. |
+| `themelia-ui/style.css` | Everything: `core.css` and the rules of every module. |
 
 ### On the server and in tests
 
-The package is ES modules, and because its JavaScript imports no CSS, Node loads it as it is.
-Server rendering and Vitest need no configuration for it, and CommonJS code on Node 20.19 or
-later can `require()` it. Jest transforms nothing in `node_modules` by default: exempt the
-package in `transformIgnorePatterns`.
+The package is ES modules. Outside a bundler its CSS imports resolve to an empty module, so
+Node loads it without the CSS: Vitest needs no configuration, CommonJS code on Node 20.19 or
+later can `require()` it, and a server render gets the CSS from the client build, or from
+Vite through `ssr.noExternal` as above. Jest needs 29.4 or newer and transforms nothing in
+`node_modules` by default: exempt the package in `transformIgnorePatterns`.
 
 ## Imports and tiers
 
@@ -122,7 +114,7 @@ up to complete blocks:
 | Base | One control or concept, including `Text` and `Heading` | `themelia-ui/base/<module>` |
 | Layout | Page and application shells | `themelia-ui/layout/<module>` |
 | Features | An interaction lifecycle with controlled state | `themelia-ui/features/<module>` |
-| Blocks | Subject-shaped compositions of the tiers above | `themelia-ui/patterns/<module>`, `themelia-ui/admin/patterns/<module>` |
+| Blocks | Subject-shaped compositions of the tiers above | `themelia-ui/blocks/<module>`, `themelia-ui/blocks/admin/<module>` |
 
 ```ts
 import { UIProvider } from "themelia-ui/ui-provider"
@@ -130,7 +122,7 @@ import { Money } from "themelia-ui/primitives"
 import { Button } from "themelia-ui/base/buttons"
 import { Page } from "themelia-ui/layout/page"
 import { DataTable } from "themelia-ui/features/table"
-import { MetricGrid } from "themelia-ui/patterns/analytics"
+import { MetricGrid } from "themelia-ui/blocks/analytics"
 ```
 
 There are no tier barrels: `themelia-ui/base` does not exist, so one import never pulls in a
@@ -163,25 +155,22 @@ A nested `UIProvider` themes one region, and inherits whatever it does not set.
 control, `UIRoot`, `UIScope`, `Scope` and `UIPortalHost` each do one of its jobs; see
 [Provider and scoping](docs/learn/provider-and-scoping.md).
 
-From CSS, set raw values such as radii and fonts on `:root`. Semantic colours such as
-`--primary`, `--background` and `--border` are derived again at every theme boundary, so
-declare them on the same selector list the package uses:
+From CSS, set any theme variable on `:root`. A colour holds both modes as
+`light-dark(light, dark)`, and each element's `color-scheme` picks the half, so one
+declaration reaches every region, a dark region inside a light page included:
 
 ```css
 :root {
   --radius: 1rem;
   --radius-sm: 0.5rem;
-}
-
-:root, [data-ui-scope], [data-density], [data-theme], .light, .dark {
-  --primary: oklch(0.55 0.19 250);
-  --primary-foreground: oklch(0.985 0 0);
+  --primary: light-dark(oklch(0.55 0.19 250), oklch(0.72 0.14 250));
+  --primary-foreground: light-dark(oklch(0.985 0 0), oklch(0.2 0.03 250));
 }
 ```
 
-The default theme answers three dark-mode signals: `class="dark"`, `data-theme="dark"` and,
-with `colorScheme: "system"`, the operating system's preference. A dark value of your own
-should answer all three.
+A colour given one value is used in both modes. Dark mode follows `class="dark"`,
+`data-theme="dark"` or, with `colorScheme: "system"`, the operating system's preference: each
+sets `color-scheme`, and nothing is declared twice.
 
 Beyond a few variables:
 
@@ -202,20 +191,19 @@ the bridge in the CSS entry that loads Tailwind:
 
 ```css
 @import "tailwindcss";
-@import "themelia-ui/style.css";
 @import "themelia-ui/tailwind.css";
 ```
 
-If the application loads module stylesheets instead of `style.css`, import
-`themelia-ui/core.css` in its place.
+The kit's own CSS arrives with its components. Do not `@import` `themelia-ui/style.css` or
+`themelia-ui/core.css` here as well: that inlines a second copy.
 
 The bridge is a Tailwind theme declaration generated from Themelia's variables. It does two
 things:
 
-1. Utilities read the live theme. `bg-primary`, `text-muted-foreground`, `rounded-sm` (the
-   item radius), `rounded-(--radius)` (the container radius), `p-md` and `shadow-lg` resolve
-   through Themelia's variables at the element, so they follow dark mode, nested providers
-   and density.
+1. Utilities read the live theme. `bg-primary`, `text-muted-foreground`, `rounded` (the
+   container radius), `rounded-sm` (the item radius), `p-padding`, `gap-gap-sm` and
+   `shadow-lg` resolve through Themelia's variables at the element, so they follow dark mode,
+   nested providers and density.
 2. It keeps Tailwind's defaults from replacing the variables both define, such as
    `--radius-sm`, `--text-sm` and `--font-sans`. Import it even if you never write one of
    its utilities.
@@ -225,7 +213,7 @@ so a utility in `className` overrides a component's own rule. There is no need f
 `!important` or `tailwind-merge`.
 
 ```tsx
-<Button className="rounded-pill px-lg shadow-lg">Approve</Button>
+<Button className="rounded-pill px-padding shadow-lg">Approve</Button>
 ```
 
 ## Overrides
@@ -265,11 +253,8 @@ action semantics, focus and the theme:
 
 ```tsx
 import { Button } from "themelia-ui/base/buttons"
-import "themelia-ui/base/buttons.css"
 import { MetadataList } from "themelia-ui/base/display"
-import "themelia-ui/base/display.css"
 import { Page } from "themelia-ui/layout/page"
-import "themelia-ui/layout/page.css"
 
 function InvoiceDetail({ invoice, onCollectPayment }) {
   return (
@@ -307,8 +292,8 @@ Search the catalogue that ships with the package, offline, by what the interface
 node node_modules/themelia-ui/scripts/consumer/find-component.mjs "mobile filters for a table" --explain
 ```
 
-Each match comes with its exact JavaScript and CSS imports and guidance on when to choose it
-and when to avoid it. `--json` prints complete records, and `--help` lists the filters.
+Each match comes with its exact import and guidance on when to choose it and when to avoid
+it. `--json` prints complete records, and `--help` lists the filters.
 
 The package also ships a skill for coding assistants, built from the same catalogue:
 
@@ -329,18 +314,21 @@ Guides:
 - [Theming and Tailwind CSS v4](docs/learn/theming.md)
 - [Provider and scoping](docs/learn/provider-and-scoping.md)
 - [Composition](docs/learn/composition.md)
+- [Structure, spacing and responsive widths](docs/learn/structure-and-spacing.md)
+- [Choosing and composing blocks](docs/learn/blocks.md)
 - [Framework wiring](docs/learn/framework-wiring.md)
 - [Forms](docs/learn/forms.md)
 - [Localization](docs/learn/i18n.md)
 - [Troubleshooting](docs/learn/troubleshooting.md)
 - [Verifying a consuming application](docs/learn/verification.md)
+- [Complete reference workflows](docs/learn/reference-workflows.md)
 
 Reference, generated from the source when the package is built. It ships in the package
 under `node_modules/themelia-ui/docs`, and the links open the latest published copy:
 
 - [Component catalogue](https://unpkg.com/themelia-ui/docs/generated/components/INDEX.md)
 - [Public API index](https://unpkg.com/themelia-ui/docs/generated/public-api.md)
-- [JavaScript, CSS and optional-peer imports](https://unpkg.com/themelia-ui/docs/generated/imports.md)
+- [Imports and optional peers](https://unpkg.com/themelia-ui/docs/generated/imports.md)
 - [Theme variables](src/styles/TOKENS.md)
 - [Recipes](https://unpkg.com/themelia-ui/docs/build/recipes.md)