themelia-ui 3.0.0 → 3.2.0

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

@@ -69,9 +69,10 @@ consumer on plain state never resolves react-hook-form.
 
 ## Field chrome
 
-`FormField` renders exactly **one** supporting line, resolved as `error || helperText ||
-hint`. They replace each other rather than stacking, so a field never grows or shifts as
-validation state changes. It also owns the wiring: it associates the label, points
+`FormField` renders at most **one** supporting message, resolved as `error || helperText ||
+hint`. They replace each other rather than stacking. A message can wrap, and adding or
+changing it can change field height; check long translated errors at narrow widths.
+It also owns the wiring: it associates the label, points
 `aria-describedby` at the supporting line, and sets `aria-invalid` on the control when there
 is an error, without overriding any of these that the caller set explicitly. Errors are
 announced politely (`role="status"`), so validation firing on each keystroke does not
@@ -80,6 +81,25 @@ interrupt typing.
 `FieldGroup` covers several controls sharing one label and one supporting line — a date
 range, a name split in two.
 
+## Sections and completion
+
+Use FormSection for an editable region inside a form, Card for an independent subject,
+and ContentBlock for supporting read-only prose. Flat FormSections retain region padding;
+an enclosing Stack can use `gap="none"` when that padding supplies the desired separation.
+FieldGroup supplies fieldset/legend semantics. Each child FormField still needs a distinct
+label. A section heading is not a field label.
+
+A resolved promise is not evidence that validation succeeded. ActionDialog normally closes
+after its confirmation callback resolves. Set `closeOnAsyncComplete={false}` when the app
+resolves with errors, and close controlled `open` only after explicit success. For a native
+form, use `formId` to associate the dialog's submit action with that form; avoid also invoking
+the mutation in `onConfirm`. Native constraint validation, the submit handler and domain
+validation then each have one owner. Prevent duplicate submissions while pending, retain
+drafts after rejection and associate errors with the relevant field or root region.
+
+See the complete [multi-section form and nested action](reference-workflows.md) sources.
+For the inset and gap contract, see [Structure and spacing](structure-and-spacing.md#use-the-two-spacing-roles).
+
 ## Generated forms
 
 When the fields come from a schema at runtime, use `features/schema-form`. When they are

package/.agents/skills/themelia-ui/references/framework-wiring.md

@@ -22,7 +22,9 @@ cells. Write it once:
 import type { LinkRenderer } from "themelia-ui/layout/sidebar"
 
 export const renderLink: LinkRenderer = ({ href, children, active, disabled, external, ...rest }) =>
-  disabled || !href ? <span {...rest}>{children}</span> : <AppLink to={href} {...rest}>{children}</AppLink>
+  disabled || !href ? <span {...rest}>{children}</span>
+    : external ? <a href={href} {...rest}>{children}</a>
+    : <AppLink to={href} {...rest}>{children}</AppLink>
 ```
 
 Return one element and spread the rest of the props onto it: they carry the class, the
@@ -50,6 +52,20 @@ async lifecycle; the application decides cache invalidation, retries, and error
 </ResourceIndexShell>
 ```
 
+## Lookup and navigation lifetimes
+
+Pass a stable `scopeKey` to ResourceCombobox, SuggestionsCombobox or useSuggestions when the lookup's workspace, locale or
+permission context changes. Changing callback identity alone does not refetch. A scope
+change aborts old work, hides old results/errors and refetches an eligible open query while
+retaining query, controlled value and open state. Late responses from an old scope cannot
+complete the current lookup. The app owns whether the selected id remains valid.
+
+Sidebar workspace disclosure keeps the mobile sheet open. A selected workspace marked
+`external: false` dismisses the sheet after selection; external destinations retain native
+target/rel behavior. Forward renderer props, including the click handler, to the real link.
+The app's router handles same-app addresses and preserves modifiers and new-tab gestures.
+See the [workspace reference](reference-workflows.md).
+
 ## Permissions
 
 Resolve authorization before constructing actions. Omit an action the user cannot perform;
@@ -58,29 +74,41 @@ through the module's tooltip or description seam.
 
 ## Translation
 
-Supply user-facing package copy through each component's `strings` prop. Keep product copy
+Supply component-owned copy through the selected API's documented `strings` prop. Passive
+components whose copy comes from children need no strings object. Keep product copy
 in application data or children. The default objects are exported so a locale can start
 from the complete shape rather than guessing keys; see [Internationalization](i18n.md).
 
 ## Server rendering and client boundaries
 
-Import server-pure formatting modules freely. Interactive modules carry their own
-`"use client"` boundary in the published entrypoint. Do not wrap the whole package in one
-client module: exact subpaths keep server-pure imports server-pure and optional peers
-isolated.
+Interactive and provider-dependent entrypoints carry `"use client"`, including
+`themelia-ui/primitives` and `themelia-ui/ui-provider`; passive modules such as
+`themelia-ui/base/structure` can remain server-pure. Inspect the exact published entrypoint
+rather than inferring its boundary from its name. In a React Server Components framework, a server component
+can render those client components with serializable props; callbacks, hooks and live
+controlled state belong in an application client component. A provider can receive server
+rendered children, so keep the boundary around the interactive region rather than the whole
+page. Check your framework's serialization rules for config containing functions or modules.
+
+Formatting helpers exported from `primitives` share its client boundary: do not call them
+from an RSC server component as if they came from a server-pure subpath. Format server data
+with the application's server utilities or render the corresponding display primitive.
+`themelia-ui/theming` exports pure derivation helpers without a client directive. Exact
+subpaths also keep optional peers isolated. Ordinary Node SSR can load and render the
+component modules; that does not make their exports server-callable in RSC.
 
 For CSP, portals, nested theme regions, and defaults, use
 [Provider and scoping](provider-and-scoping.md). Do not recreate provider context in an
 application adapter unless the documented public hooks are insufficient.
 
-## Vite, Next.js, and CSS entrypoints
+## Vite, Next.js, and CSS
 
-The JavaScript imports no CSS: import the exact module stylesheet beside the component. In a
-framework that restricts where global CSS may be imported, collect the same module
-stylesheets in its permitted application or route-layout entry. Do not replace them with
-source paths. `style.css` loads every module; prefer module stylesheets when a route uses a
-few. Server rendering and test runners are covered in
-[Loading the CSS](installation.md#loading-the-css).
+A component brings its own CSS, so there is no stylesheet to collect: it arrives through the
+component's JavaScript, which your bundler processes. Frameworks that render on the server
+with Vite, such as Astro, React Router, TanStack Start and Vike, list the package in
+`ssr.noExternal`; see [Server rendering with Vite](installation.md#server-rendering-with-vite).
+Parcel needs its `packageExports` option. Next.js needs nothing. Pages with no bundler link
+`style.css`.
 
 Server-rendered HTML and the client bundle must load the same theme tokens before hydration.
 Apply the theme attribute and provider configuration from the same persisted value to avoid

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

@@ -5,8 +5,10 @@ overridable, and nothing in it inspects `navigator.language` or imports a transl
 
 ## Strings
 
-Each module exports a `*Strings` interface and a `default*Strings` object, and its
-components take a `strings` prop:
+Components that own visible or accessible copy document a `strings` prop; their modules
+export the matching `*Strings` interface and `default*Strings` object. Passive structures
+and components whose copy comes entirely from children need no strings object. Read the
+selected API rather than adding `strings` by analogy:
 
 ```tsx fragment — shape only, not a program
 <Copyable strings={{ copy: "Kopieren", copied: "Kopiert" }} value={apiKey} />

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

@@ -6,115 +6,115 @@ Every module has one subpath. There are no tier barrels: `themelia-ui/base` and
 siblings do not exist, because one specifier would pull an entire tier and every optional
 peer inside it. The root carries the provider and the display primitives, both peer-free.
 
-Import the stylesheet column beside the exact JavaScript subpath, or `style.css` once. The
-JavaScript imports no CSS, so a module without its stylesheet renders unstyled.
+A component brings its own CSS in a bundled app. Pages with no bundler link `style.css`; see
+[Installation](installation.md).
 
 ## general profile — 95 modules
 
-| module | import | stylesheet | optional peers |
-| --- | --- | --- | --- |
-| `base/accordion` | `themelia-ui/base/accordion` | `themelia-ui/base/accordion.css` | — |
-| `base/action-menu` | `themelia-ui/base/action-menu` | `themelia-ui/base/action-menu.css` | — |
-| `base/alert-dialog` | `themelia-ui/base/alert-dialog` | `themelia-ui/base/alert-dialog.css` | — |
-| `base/aspect-ratio` | `themelia-ui/base/aspect-ratio` | `themelia-ui/base/aspect-ratio.css` | — |
-| `base/avatar` | `themelia-ui/base/avatar` | `themelia-ui/base/avatar.css` | — |
-| `base/badge` | `themelia-ui/base/badge` | `themelia-ui/base/badge.css` | — |
-| `base/batch-action-bar` | `themelia-ui/base/batch-action-bar` | `themelia-ui/base/batch-action-bar.css` | — |
-| `base/buttons` | `themelia-ui/base/buttons` | `themelia-ui/base/buttons.css` | — |
-| `base/cards` | `themelia-ui/base/cards` | `themelia-ui/base/cards.css` | — |
-| `base/carousel` | `themelia-ui/base/carousel` | `themelia-ui/base/carousel.css` | — |
-| `base/chart` | `themelia-ui/base/chart` | `themelia-ui/base/chart.css` | recharts |
-| `base/choice-inputs` | `themelia-ui/base/choice-inputs` | `themelia-ui/base/choice-inputs.css` | — |
-| `base/combobox` | `themelia-ui/base/combobox` | `themelia-ui/base/combobox.css` | — |
-| `base/command` | `themelia-ui/base/command` | `themelia-ui/base/command.css` | — |
-| `base/context-menu` | `themelia-ui/base/context-menu` | `themelia-ui/base/context-menu.css` | — |
-| `base/copyable` | `themelia-ui/base/copyable` | `themelia-ui/base/copyable.css` | — |
-| `base/date-pickers` | `themelia-ui/base/date-pickers` | `themelia-ui/base/date-pickers.css` | — |
-| `base/dialog` | `themelia-ui/base/dialog` | `themelia-ui/base/dialog.css` | — |
-| `base/direction` | `themelia-ui/base/direction` | — | — |
-| `base/display` | `themelia-ui/base/display` | `themelia-ui/base/display.css` | — |
-| `base/dropdown-menu` | `themelia-ui/base/dropdown-menu` | `themelia-ui/base/dropdown-menu.css` | — |
-| `base/feedback` | `themelia-ui/base/feedback` | `themelia-ui/base/feedback.css` | — |
-| `base/forms` | `themelia-ui/base/forms` | `themelia-ui/base/forms.css` | — |
-| `base/forms-numeric` | `themelia-ui/base/forms-numeric` | `themelia-ui/base/forms-numeric.css` | — |
-| `base/hover-card` | `themelia-ui/base/hover-card` | `themelia-ui/base/hover-card.css` | — |
-| `base/input-group` | `themelia-ui/base/input-group` | `themelia-ui/base/input-group.css` | — |
-| `base/item` | `themelia-ui/base/item` | `themelia-ui/base/item.css` | — |
-| `base/label` | `themelia-ui/base/label` | `themelia-ui/base/label.css` | — |
-| `base/menubar` | `themelia-ui/base/menubar` | `themelia-ui/base/menubar.css` | — |
-| `base/navigation` | `themelia-ui/base/navigation` | `themelia-ui/base/navigation.css` | — |
-| `base/navigation-menu` | `themelia-ui/base/navigation-menu` | `themelia-ui/base/navigation-menu.css` | — |
-| `base/otp-input` | `themelia-ui/base/otp-input` | `themelia-ui/base/otp-input.css` | — |
-| `base/overlay` | `themelia-ui/base/overlay` | `themelia-ui/base/overlay.css` | — |
-| `base/popover` | `themelia-ui/base/popover` | `themelia-ui/base/popover.css` | — |
-| `base/popover-menu` | `themelia-ui/base/popover-menu` | `themelia-ui/base/popover-menu.css` | — |
-| `base/qr-code` | `themelia-ui/base/qr-code` | `themelia-ui/base/qr-code.css` | — |
-| `base/repeaters` | `themelia-ui/base/repeaters` | `themelia-ui/base/repeaters.css` | — |
-| `base/resizable` | `themelia-ui/base/resizable` | `themelia-ui/base/resizable.css` | — |
-| `base/sheet` | `themelia-ui/base/sheet` | `themelia-ui/base/sheet.css` | — |
-| `base/sidebar` | `themelia-ui/base/sidebar` | `themelia-ui/base/sidebar.css` | — |
-| `base/skeleton` | `themelia-ui/base/skeleton` | `themelia-ui/base/skeleton.css` | — |
-| `base/slot` | `themelia-ui/base/slot` | — | — |
-| `base/spinner` | `themelia-ui/base/spinner` | `themelia-ui/base/spinner.css` | — |
-| `base/structure` | `themelia-ui/base/structure` | `themelia-ui/base/structure.css` | — |
-| `base/table` | `themelia-ui/base/table` | `themelia-ui/base/table.css` | — |
-| `base/text-inputs` | `themelia-ui/base/text-inputs` | `themelia-ui/base/text-inputs.css` | — |
-| `base/timeline` | `themelia-ui/base/timeline` | `themelia-ui/base/timeline.css` | — |
-| `base/toaster` | `themelia-ui/base/toaster` | `themelia-ui/base/toaster.css` | — |
-| `base/toggle` | `themelia-ui/base/toggle` | `themelia-ui/base/toggle.css` | — |
-| `base/toolbar` | `themelia-ui/base/toolbar` | `themelia-ui/base/toolbar.css` | — |
-| `base/tooltip` | `themelia-ui/base/tooltip` | `themelia-ui/base/tooltip.css` | — |
-| `base/typography` | `themelia-ui/base/typography` | `themelia-ui/base/typography.css` | — |
-| `base/upload` | `themelia-ui/base/upload` | `themelia-ui/base/upload.css` | — |
-| `base/value-inputs` | `themelia-ui/base/value-inputs` | `themelia-ui/base/value-inputs.css` | — |
-| `features/actions` | `themelia-ui/features/actions` | `themelia-ui/features/actions.css` | — |
-| `features/activities` | `themelia-ui/features/activities` | `themelia-ui/features/activities.css` | @tiptap/core, @tiptap/pm, @tiptap/starter-kit |
-| `features/ai-chat` | `themelia-ui/features/ai-chat` | `themelia-ui/features/ai-chat.css` | — |
-| `features/async-preview` | `themelia-ui/features/async-preview` | `themelia-ui/features/async-preview.css` | — |
-| `features/combobox` | `themelia-ui/features/combobox` | `themelia-ui/features/combobox.css` | — |
-| `features/comments` | `themelia-ui/features/comments` | `themelia-ui/features/comments.css` | @tiptap/core, @tiptap/pm, @tiptap/starter-kit |
-| `features/data-view` | `themelia-ui/features/data-view` | `themelia-ui/features/data-view.css` | @tanstack/react-table |
-| `features/event-calendar` | `themelia-ui/features/event-calendar` | `themelia-ui/features/event-calendar.css` | — |
-| `features/filters` | `themelia-ui/features/filters` | `themelia-ui/features/filters.css` | — |
-| `features/global-search` | `themelia-ui/features/global-search` | `themelia-ui/features/global-search.css` | — |
-| `features/kanban` | `themelia-ui/features/kanban` | `themelia-ui/features/kanban.css` | @dnd-kit/core, @dnd-kit/sortable, @dnd-kit/utilities |
-| `features/map` | `themelia-ui/features/map` | `themelia-ui/features/map.css` | leaflet, leaflet-draw, leaflet.fullscreen, leaflet.markercluster, react-leaflet, react-leaflet-markercluster |
-| `features/media-library` | `themelia-ui/features/media-library` | `themelia-ui/features/media-library.css` | — |
-| `features/mentions` | `themelia-ui/features/mentions` | `themelia-ui/features/mentions.css` | — |
-| `features/overlays` | `themelia-ui/features/overlays` | `themelia-ui/features/overlays.css` | — |
-| `features/products` | `themelia-ui/features/products` | `themelia-ui/features/products.css` | @tanstack/react-table |
-| `features/resource` | `themelia-ui/features/resource` | `themelia-ui/features/resource.css` | — |
-| `features/resource-assignment` | `themelia-ui/features/resource-assignment` | `themelia-ui/features/resource-assignment.css` | — |
-| `features/rich-text-editor` | `themelia-ui/features/rich-text-editor` | `themelia-ui/features/rich-text-editor.css` | @tiptap/core, @tiptap/pm, @tiptap/starter-kit |
-| `features/rich-text-editor/tiptap` | `themelia-ui/features/rich-text-editor/tiptap` | — | @tiptap/core, @tiptap/pm, @tiptap/starter-kit |
-| `features/schema-form` | `themelia-ui/features/schema-form` | `themelia-ui/features/schema-form.css` | — |
-| `features/sync` | `themelia-ui/features/sync` | `themelia-ui/features/sync.css` | react-hook-form |
-| `features/table` | `themelia-ui/features/table` | `themelia-ui/features/table.css` | @tanstack/react-table |
-| `features/theme-tweaker` | `themelia-ui/features/theme-tweaker` | `themelia-ui/features/theme-tweaker.css` | — |
-| `forms` | `themelia-ui/forms` | — | — |
-| `forms-rhf` | `themelia-ui/forms-rhf` | — | react-hook-form |
-| `layout/app-shell` | `themelia-ui/layout/app-shell` | `themelia-ui/layout/app-shell.css` | — |
-| `layout/auth` | `themelia-ui/layout/auth` | `themelia-ui/layout/auth.css` | — |
-| `layout/containers` | `themelia-ui/layout/containers` | `themelia-ui/layout/containers.css` | — |
-| `layout/header` | `themelia-ui/layout/header` | `themelia-ui/layout/header.css` | — |
-| `layout/navigation` | `themelia-ui/layout/navigation` | `themelia-ui/layout/navigation.css` | — |
-| `layout/page` | `themelia-ui/layout/page` | `themelia-ui/layout/page.css` | — |
-| `layout/settings` | `themelia-ui/layout/settings` | `themelia-ui/layout/settings.css` | — |
-| `layout/sidebar` | `themelia-ui/layout/sidebar` | `themelia-ui/layout/sidebar.css` | — |
-| `layout/workspace` | `themelia-ui/layout/workspace` | `themelia-ui/layout/workspace.css` | — |
-| `patterns/analytics` | `themelia-ui/patterns/analytics` | `themelia-ui/patterns/analytics.css` | recharts |
-| `patterns/onboarding` | `themelia-ui/patterns/onboarding` | `themelia-ui/patterns/onboarding.css` | — |
-| `patterns/timelines` | `themelia-ui/patterns/timelines` | `themelia-ui/patterns/timelines.css` | — |
-| `primitives` | `themelia-ui/primitives` | `themelia-ui/primitives.css` | — |
-| `theming` | `themelia-ui/theming` | — | — |
-| `ui-provider` | `themelia-ui/ui-provider` | — | — |
+| module | import | optional peers |
+| --- | --- | --- |
+| `base/accordion` | `themelia-ui/base/accordion` | — |
+| `base/action-menu` | `themelia-ui/base/action-menu` | — |
+| `base/alert-dialog` | `themelia-ui/base/alert-dialog` | — |
+| `base/aspect-ratio` | `themelia-ui/base/aspect-ratio` | — |
+| `base/avatar` | `themelia-ui/base/avatar` | — |
+| `base/badge` | `themelia-ui/base/badge` | — |
+| `base/batch-action-bar` | `themelia-ui/base/batch-action-bar` | — |
+| `base/buttons` | `themelia-ui/base/buttons` | — |
+| `base/cards` | `themelia-ui/base/cards` | — |
+| `base/carousel` | `themelia-ui/base/carousel` | — |
+| `base/chart` | `themelia-ui/base/chart` | recharts |
+| `base/choice-inputs` | `themelia-ui/base/choice-inputs` | — |
+| `base/combobox` | `themelia-ui/base/combobox` | — |
+| `base/command` | `themelia-ui/base/command` | — |
+| `base/context-menu` | `themelia-ui/base/context-menu` | — |
+| `base/copyable` | `themelia-ui/base/copyable` | — |
+| `base/date-pickers` | `themelia-ui/base/date-pickers` | — |
+| `base/dialog` | `themelia-ui/base/dialog` | — |
+| `base/direction` | `themelia-ui/base/direction` | — |
+| `base/display` | `themelia-ui/base/display` | — |
+| `base/dropdown-menu` | `themelia-ui/base/dropdown-menu` | — |
+| `base/feedback` | `themelia-ui/base/feedback` | — |
+| `base/forms` | `themelia-ui/base/forms` | — |
+| `base/forms-numeric` | `themelia-ui/base/forms-numeric` | — |
+| `base/hover-card` | `themelia-ui/base/hover-card` | — |
+| `base/input-group` | `themelia-ui/base/input-group` | — |
+| `base/item` | `themelia-ui/base/item` | — |
+| `base/label` | `themelia-ui/base/label` | — |
+| `base/menubar` | `themelia-ui/base/menubar` | — |
+| `base/navigation` | `themelia-ui/base/navigation` | — |
+| `base/navigation-menu` | `themelia-ui/base/navigation-menu` | — |
+| `base/otp-input` | `themelia-ui/base/otp-input` | — |
+| `base/overlay` | `themelia-ui/base/overlay` | — |
+| `base/popover` | `themelia-ui/base/popover` | — |
+| `base/popover-menu` | `themelia-ui/base/popover-menu` | — |
+| `base/qr-code` | `themelia-ui/base/qr-code` | — |
+| `base/repeaters` | `themelia-ui/base/repeaters` | — |
+| `base/resizable` | `themelia-ui/base/resizable` | — |
+| `base/sheet` | `themelia-ui/base/sheet` | — |
+| `base/sidebar` | `themelia-ui/base/sidebar` | — |
+| `base/skeleton` | `themelia-ui/base/skeleton` | — |
+| `base/slot` | `themelia-ui/base/slot` | — |
+| `base/spinner` | `themelia-ui/base/spinner` | — |
+| `base/structure` | `themelia-ui/base/structure` | — |
+| `base/table` | `themelia-ui/base/table` | — |
+| `base/text-inputs` | `themelia-ui/base/text-inputs` | — |
+| `base/timeline` | `themelia-ui/base/timeline` | — |
+| `base/toaster` | `themelia-ui/base/toaster` | — |
+| `base/toggle` | `themelia-ui/base/toggle` | — |
+| `base/toolbar` | `themelia-ui/base/toolbar` | — |
+| `base/tooltip` | `themelia-ui/base/tooltip` | — |
+| `base/typography` | `themelia-ui/base/typography` | — |
+| `base/upload` | `themelia-ui/base/upload` | — |
+| `base/value-inputs` | `themelia-ui/base/value-inputs` | — |
+| `blocks/analytics` | `themelia-ui/blocks/analytics` | recharts |
+| `blocks/onboarding` | `themelia-ui/blocks/onboarding` | — |
+| `blocks/timelines` | `themelia-ui/blocks/timelines` | — |
+| `features/actions` | `themelia-ui/features/actions` | — |
+| `features/activities` | `themelia-ui/features/activities` | @tiptap/core, @tiptap/pm, @tiptap/starter-kit |
+| `features/ai-chat` | `themelia-ui/features/ai-chat` | — |
+| `features/async-preview` | `themelia-ui/features/async-preview` | — |
+| `features/combobox` | `themelia-ui/features/combobox` | — |
+| `features/comments` | `themelia-ui/features/comments` | @tiptap/core, @tiptap/pm, @tiptap/starter-kit |
+| `features/data-view` | `themelia-ui/features/data-view` | @tanstack/react-table |
+| `features/event-calendar` | `themelia-ui/features/event-calendar` | — |
+| `features/filters` | `themelia-ui/features/filters` | — |
+| `features/global-search` | `themelia-ui/features/global-search` | — |
+| `features/kanban` | `themelia-ui/features/kanban` | @dnd-kit/core, @dnd-kit/sortable, @dnd-kit/utilities |
+| `features/map` | `themelia-ui/features/map` | leaflet, leaflet-draw, leaflet.fullscreen, leaflet.markercluster, react-leaflet, react-leaflet-markercluster |
+| `features/media-library` | `themelia-ui/features/media-library` | — |
+| `features/mentions` | `themelia-ui/features/mentions` | — |
+| `features/overlays` | `themelia-ui/features/overlays` | — |
+| `features/products` | `themelia-ui/features/products` | @tanstack/react-table |
+| `features/resource` | `themelia-ui/features/resource` | — |
+| `features/resource-assignment` | `themelia-ui/features/resource-assignment` | — |
+| `features/rich-text-editor` | `themelia-ui/features/rich-text-editor` | @tiptap/core, @tiptap/pm, @tiptap/starter-kit |
+| `features/rich-text-editor/tiptap` | `themelia-ui/features/rich-text-editor/tiptap` | @tiptap/core, @tiptap/pm, @tiptap/starter-kit |
+| `features/schema-form` | `themelia-ui/features/schema-form` | — |
+| `features/sync` | `themelia-ui/features/sync` | react-hook-form |
+| `features/table` | `themelia-ui/features/table` | @tanstack/react-table |
+| `features/theme-tweaker` | `themelia-ui/features/theme-tweaker` | — |
+| `forms` | `themelia-ui/forms` | — |
+| `forms-rhf` | `themelia-ui/forms-rhf` | react-hook-form |
+| `layout/app-shell` | `themelia-ui/layout/app-shell` | — |
+| `layout/auth` | `themelia-ui/layout/auth` | — |
+| `layout/containers` | `themelia-ui/layout/containers` | — |
+| `layout/header` | `themelia-ui/layout/header` | — |
+| `layout/navigation` | `themelia-ui/layout/navigation` | — |
+| `layout/page` | `themelia-ui/layout/page` | — |
+| `layout/settings` | `themelia-ui/layout/settings` | — |
+| `layout/sidebar` | `themelia-ui/layout/sidebar` | — |
+| `layout/workspace` | `themelia-ui/layout/workspace` | — |
+| `primitives` | `themelia-ui/primitives` | — |
+| `theming` | `themelia-ui/theming` | — |
+| `ui-provider` | `themelia-ui/ui-provider` | — |
 
 ## admin profile — 2 modules
 
-| module | import | stylesheet | optional peers |
-| --- | --- | --- | --- |
-| `admin/patterns/access` | `themelia-ui/admin/patterns/access` | `themelia-ui/admin/patterns/access.css` | — |
-| `admin/patterns/commerce` | `themelia-ui/admin/patterns/commerce` | `themelia-ui/admin/patterns/commerce.css` | — |
+| module | import | optional peers |
+| --- | --- | --- |
+| `blocks/admin/access` | `themelia-ui/blocks/admin/access` | — |
+| `blocks/admin/commerce` | `themelia-ui/blocks/admin/commerce` | — |
 
 ## Optional peers — 15 of them
 
@@ -137,4 +137,4 @@ resolves it. Release verification rejects a module that reaches an undeclared pe
 | `react-hook-form` | `features/sync`, `forms-rhf` |
 | `react-leaflet` | `features/map` |
 | `react-leaflet-markercluster` | `features/map` |
-| `recharts` | `base/chart`, `patterns/analytics` |
+| `recharts` | `base/chart`, `blocks/analytics` |

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

@@ -4,16 +4,19 @@
 npm install themelia-ui
 ```
 
-React 19 and `react-dom` are required peers. Everything else is optional and only pulled in
-by the module that needs it; see [Optional peers](#optional-peers).
+React 19 and `react-dom` are required peers. The package's regular dependencies install
+automatically; additional peer packages are optional and resolved only by the modules
+that need them. See [Optional peers](#optional-peers).
 
 ## Browser support
 
-Chrome and Edge 125, Firefox 121 and Safari 16.4 or newer. The stylesheets rely on
-`round()`, `:has()`, `:dir()` and `color-mix()` with no fallback below those versions.
-Entrance transitions use `@starting-style` and simply don't animate where it is missing.
-If your bundler lowers CSS for older targets, keep `:dir()` out of it: lowered, it becomes a
-list of right-to-left languages and ignores `dir="rtl"`.
+Chrome and Edge 125, Firefox 121 and Safari 17.5 or newer. The stylesheets rely on
+`round()`, `:has()`, `:dir()`, `color-mix()` and `light-dark()` with no fallback below those
+versions. Entrance transitions use `@starting-style` and simply don't animate where it is
+missing. If your bundler lowers CSS for older targets, keep `:dir()` and `light-dark()` out of
+it: lowered, `:dir()` becomes a list of right-to-left languages and ignores `dir="rtl"`, and
+`light-dark()` resolves where a theme variable is declared, so a dark region inside a light
+page keeps the light colours.
 
 ## Import exactly what you use
 
@@ -36,41 +39,67 @@ The exact import for every module is in
 
 ## Loading the CSS
 
-The package ships three kinds of stylesheet:
+### In a bundled app
 
-| Import | Contains |
-| --- | --- |
-| `themelia-ui/<module>.css` | `core.css`, then the rules of the module and of the modules it draws with |
-| `themelia-ui/style.css` | `core.css` and every module, in one file |
-| `themelia-ui/core.css` | Tokens, themes, typefaces, the base reset and the cascade layer order; no component rules |
+A component brings its own CSS. Import it from its subpath and nothing else: Vite, webpack,
+Rspack and the frameworks built on them, such as Next.js and React Router, add its stylesheet
+with its JavaScript, include each stylesheet once however many components need it, and leave
+out the CSS of any module the application never imports. Your bundler processes the kit's CSS
+like your own, so the note on lowering under [Browser support](#browser-support) applies to it.
+
+Do not also import `themelia-ui/style.css` or a module stylesheet from JavaScript; that loads
+the same rules twice. The upgrade codemod removes those imports.
 
-[`imports.md`](imports.md) gives each module's stylesheet path. A module whose
-components draw nothing has no stylesheet.
+Parcel reads a package's `exports` only when the application's `package.json` sets
+`"@parcel/resolver-default": { "packageExports": true }`.
 
-### Import the stylesheets
+### Server rendering with Vite
+
+Astro, React Router, TanStack Start, Vike and other frameworks that render on the server with
+Vite hand installed packages to Node, which loads the kit without its CSS. List `themelia-ui`,
+and any installed package that imports it, in `ssr.noExternal`, so Vite processes it:
+
+```ts fragment — the consuming application's bundler config, not compiled against the package
+// vite.config.ts, or the `vite` key of astro.config.mjs
+export default {
+  ssr: { noExternal: ["themelia-ui"] },
+}
+```
 
-The JavaScript imports no CSS. Import each module's stylesheet beside its JavaScript, as the
-examples in these docs do, or `style.css` once. Vite, webpack, Rspack, Next.js and other
-bundlers that handle CSS imports include each file once, however many modules import it. A
-component whose stylesheet is not imported renders unstyled.
+Astro gathers a page's CSS on the server, so without this line it renders the kit unstyled.
+React Router takes CSS from the client build; the line fixes its development server's first
+render. Next.js needs nothing.
+
+### Without a bundler
+
+A page that links stylesheets directly links `style.css`, which includes `core.css`:
+
+| Stylesheet | Contains |
+| --- | --- |
+| `themelia-ui/core.css` | Tokens, themes, typefaces, the base reset and the cascade layer order; no component rules |
+| `themelia-ui/style.css` | `core.css` and every module, in one file |
 
 ### In Node
 
-The package is ES modules, and its JavaScript imports no CSS, so Node loads it as it is:
-server rendering and test runners need no configuration for it, and CommonJS code on Node
-20.19 or later can `require()` it. Jest is the exception, because it transforms nothing in
-`node_modules` by default: exempt the package in `transformIgnorePatterns`.
+The package is ES modules. Its JavaScript imports its CSS through the package's private
+`imports` map, which resolves to an empty module outside a bundler, so Node loads it as it
+is, without the CSS. Test runners need no configuration for it, and CommonJS code on Node
+20.19 or later can `require()` it; a server render needs configuration only where the
+framework gathers CSS on the server, as in
+[Server rendering with Vite](#server-rendering-with-vite). Jest is the exception: it needs
+29.4 or newer, which resolves the `imports` map, and it transforms nothing in `node_modules`
+by default, so exempt the package in `transformIgnorePatterns`.
 
 ### `core.css` on its own
 
-Every module stylesheet begins by importing `core.css`, so a component never needs a
-separate core import to render correctly. Import `core.css` on its own when application CSS
-uses the tokens on a page without kit components, or to place the kit's layers next to
-another layered stylesheet, as in the [Tailwind setup](theming.md#tailwind-css-v4).
+Import `core.css` on its own when application CSS uses the tokens on a page without kit
+components, or to place the kit's layers next to another layered stylesheet: import it from
+JavaScript before that stylesheet. It is the file the components import, so a bundler keeps
+one copy; an `@import` from a CSS file inlines a second one.
 
 ### Overriding the kit
 
-Component rules live in the cascade layers `tokens, theming, base, components, utilities`,
+Component rules live in the cascade layers `tokens, base, components, utilities`,
 so unlayered application CSS wins over them whatever its order or specificity. Select with
 the stable `data-slot` attributes and BEM hooks such as `{name}--component`, and select a
 state with the attributes the primitives set (`data-open`, `data-checked`, `data-disabled`,
@@ -79,8 +108,8 @@ releases.
 
 ## Optional peers
 
-Every peer other than React is optional, and each is reachable only from the modules that
-use it: a consumer who never imports `features/map` never resolves Leaflet.
+Every peer other than `react` and `react-dom` is optional, and each is reachable only from
+the modules that use it: a consumer who never imports `features/map` never resolves Leaflet.
 
 The peer-to-module table is in [`docs/generated/imports.md`](imports.md).