themelia-ui 2.0.1 → 3.1.0

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

@@ -6,21 +6,35 @@ runtime. Those concerns meet through explicit props rather than hidden framework
 
 ## Routing
 
-Pass the router's link through `render` or a family's documented `renderLink` adapter. Do
-not put navigation in an `onClick` when the destination is a URL: a real link preserves
-open-in-new-tab, the status-bar destination, and browser semantics.
+Pass the router's link through `render`, or through `renderLink` where a component renders
+links of its own. Do not put navigation in an `onClick` when the destination is a URL: a
+real link preserves open-in-new-tab, the status-bar destination, and browser semantics.
 
 ```tsx fragment — replace AppLink with the link component from the consuming router
 <Button render={<AppLink to="/invoices/new" />}>New invoice</Button>
 ```
 
-Layout navigation adapters accept the same idea at the page or shell boundary. The kit does
-not import React Router, Next.js, Remix, or another router.
+Every `renderLink` takes the same function, a `LinkRenderer`: the sidebar and header, page
+headers and actions, menus and action buttons, navigation tabs, pagination, and table
+cells. Write it once:
+
+```tsx fragment — replace AppLink with the link component from the consuming router
+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>
+```
+
+Return one element and spread the rest of the props onto it: they carry the class, the
+`aria-current` of the current page and the click handler the component needs. `active`,
+`disabled` and `external` are hints to read. `Pagination` builds its addresses with
+`pageHref={(page) => ...}` and then renders them through the same `renderLink`. The kit
+does not import React Router, Next.js, Remix, or another router.
 
 ## Queries and mutations
 
 Fetch records outside the component, pass data and loading/error state in, and connect
-mutations through callbacks. A callback may return a promise when the family documents an
+mutations through callbacks. A callback may return a promise when the module documents an
 async lifecycle; the application decides cache invalidation, retries, and error reporting.
 
 ```tsx fragment — query client and mutation implementation belong to the application
@@ -40,7 +54,7 @@ async lifecycle; the application decides cache invalidation, retries, and error
 
 Resolve authorization before constructing actions. Omit an action the user cannot perform;
 disable it only when seeing the unavailable action is itself useful and provide the reason
-through the family's tooltip or description seam.
+through the module's tooltip or description seam.
 
 ## Translation
 
@@ -50,7 +64,7 @@ from the complete shape rather than guessing keys; see [Internationalization](i1
 
 ## Server rendering and client boundaries
 
-Import server-pure formatting families freely. Interactive families carry their own
+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.
@@ -59,13 +73,14 @@ 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
 
-Vite and similar bundlers can keep each exact `.css` import beside the component-family
-import. In a framework that restricts where global CSS may be imported, collect those same
-exact family stylesheets in its permitted application or route-layout entry. Do not replace
-them with source paths, and do not import `style.css` merely to avoid learning which families
-the route uses.
+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,8 @@ overridable, and nothing in it inspects `navigator.language` or imports a transl
 
 ## Strings
 
-Each family exports a `*Strings` interface and a `default*Strings` object, and takes a
-`strings` prop:
+Each module exports a `*Strings` interface and a `default*Strings` object, and its
+components take a `strings` prop:
 
 ```tsx fragment — shape only, not a program
 <Copyable strings={{ copy: "Kopieren", copied: "Kopiert" }} value={apiKey} />
@@ -19,7 +19,7 @@ partially, and every sibling key keeps its default:
 <DataTable strings={{ pagination: { previous: "Zurück", next: "Weiter" } }} />
 ```
 
-Where a family types its prop as `Partial<…Strings>`, TypeScript still asks for each nested
+Where a module types its prop as `Partial<…Strings>`, TypeScript still asks for each nested
 group whole; spread the group's default, for example
 `kind: { ...defaultTransactionStrings.kind, refund: "Rückerstattung" }`.
 
@@ -40,7 +40,7 @@ two forms. Replace the whole function, not the words inside it.
 
 ### What consumers can rely on
 
-- Component-owned visible and accessible copy belongs to the family's typed `strings`
+- Component-owned visible and accessible copy belongs to the module's typed `strings`
   contract, including placeholders, titles, alternative text, and announcements.
 - Product/domain copy still arrives through application data, children, or documented props;
   the package does not translate it or decide which message catalogue to use.

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

@@ -2,125 +2,124 @@
 
 # Exact imports
 
-Every family has one subpath. There are no layer barrels: `themelia-ui/base` and its three
-siblings were removed because one specifier pulled an entire layer and every optional peer
-inside it. The root carries the provider and the display primitives, both peer-free.
+Every module has one subpath. There are no tier barrels: `themelia-ui/base` and its three
+siblings do not exist, because one specifier would pull an entire tier and every optional
+peer inside it. The root carries the provider and the display primitives, both peer-free.
 
-Import the stylesheet column beside the exact JavaScript subpath. ESM bundlers also
-discover the family rules through the module graph, but the explicit form behaves the
-same in CJS and makes the selected CSS visible in application source.
+A component brings its own CSS in a bundled app. Pages with no bundler link `style.css`; see
+docs/learn/installation.md.
 
-## general profile — 95 families
+## general profile — 95 modules
 
-| family | 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 families
+## admin profile — 2 modules
 
-| family | 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
 
-Each is reachable only from the families below, so a consumer who never imports one never
-resolves it. Release verification rejects a family that reaches an undeclared peer.
+Each is reachable only from the modules below, so a consumer who never imports one never
+resolves it. Release verification rejects a module that reaches an undeclared peer.
 
 | peer | reachable from |
 | --- | --- |
@@ -138,4 +137,4 @@ resolves it. Release verification rejects a family 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

@@ -5,20 +5,22 @@ npm install themelia-ui
 ```
 
 React 19 and `react-dom` are required peers. Everything else is optional and only pulled in
-by the family that needs it — see [Optional peers](#optional-peers).
+by the module that needs it; 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
 
-The package publishes one subpath per family and no broad barrels: there is no
-`themelia-ui/base`, and there will not be. A barrel would pull every family into the bundle
+The package publishes one subpath per module and no broad barrels: there is no
+`themelia-ui/base`, and there will not be. A barrel would pull every module into the bundle
 and make an optional peer reachable from an import that did not ask for it.
 
 ```tsx compile
@@ -27,46 +29,88 @@ import { Stack } from "themelia-ui/base/structure"
 import { Money } from "themelia-ui/primitives"
 ```
 
-The root `themelia-ui` export exists and is optional-peer-free, but it is for
+The root `themelia-ui` export exists and is free of optional peers, but it is for
 prototyping. Shipping code should name subpaths, which keeps the JS and CSS to what you
 use.
 
-The exact import for every family is in
+The exact import for every module is in
 [`docs/generated/imports.md`](imports.md), generated from the package manifest.
 
-## CSS
+## Loading the CSS
 
-Import each family's stylesheet beside its components. The ESM build also imports its own
-CSS, but the CJS build, SSR without a CSS loader and most test runners do not; the explicit
-import behaves the same everywhere and keeps the selected CSS visible in application source.
-Each family stylesheet imports the shared tokens, themes and cascade layer order from
-`core.css` for you.
+### In a bundled app
 
-```tsx fragment — shape only, not a program
-import "themelia-ui/base/buttons.css"
+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.
+
+Parcel reads a package's `exports` only when the application's `package.json` sets
+`"@parcel/resolver-default": { "packageExports": true }`.
+
+### 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"] },
+}
 ```
 
-Import `themelia-ui/core.css` on its own only when application CSS needs the token
-contract before any family stylesheet is loaded. Do not add it merely because you imported
-a family stylesheet; that sheet already imports it.
+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. 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
 
-A family whose components draw nothing has no sheet. `imports.md` records which.
+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.
 
-If you would rather not track sheets per family, `themelia-ui/style.css` is the
-deduplicated union of all of them, larger than any one app needs.
+### Overriding the kit
 
-Import application overrides after the kit. Component rules live in cascade layers, so
-ordinary unlayered consumer CSS wins without specificity tricks. Select with stable
-`data-slot` and BEM hooks, and select a state with the attributes the primitives set
-(`data-open`, `data-checked`, `data-disabled`, `data-highlighted`, `data-popup-open`).
+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`,
+`data-highlighted`, `data-popup-open`). Hashed CSS Module class names change between
+releases.
 
 ## Optional peers
 
-Every peer other than React is optional, and each is reachable only from the families that
+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.
 
-The peer-to-family table is in [`docs/generated/imports.md`](imports.md),
-generated from and checked against the package graph.
+The peer-to-module table is in [`docs/generated/imports.md`](imports.md).
 
 The `react-hook-form` adapter, for example, lives behind its own subpath so
 `themelia-ui/forms` stays dependency-free; a consumer on plain React state never resolves
@@ -76,10 +120,10 @@ react-hook-form. See [Forms](forms.md).
 
 The package ships two profiles from one install:
 
-- **General** — typography, formatted primitives, controls, generic patterns, layout shells
+- **General**: typography, formatted primitives, controls, generic blocks, layout shells
   and domain-neutral interaction features.
-- **Admin** — B2B and admin presentation, built only from the general profile.
+- **Admin**: B2B and admin presentation, built only from the general profile.
 
-Which families belong to which is in
-`docs/generated/profiles.md` (`node_modules/themelia-ui/docs/generated/profiles.md`). An admin family may build on a
+Which modules belong to which is in
+`docs/generated/profiles.md` (`node_modules/themelia-ui/docs/generated/profiles.md`). An admin module may build on a
 general one, never the reverse.