themelia-ui 3.0.0 → 3.1.0

package/.agents/skills/themelia-ui/SKILL.md

@@ -20,7 +20,7 @@ uses CSS Modules over Base UI, publishes exact module subpaths, and has no `ui/`
 4. Prefer the highest ready module that owns the behavior, then customize it at the lowest
    sufficient extension rung: prop → provider default → slot/render prop → composition →
    consumer CSS → application-owned component.
-5. Import the exact JavaScript subpath and exact module stylesheet.
+5. Import the exact JavaScript subpath; in a bundled app its CSS comes with it.
 6. Keep application policy in the application, then verify the composed result in its real
    route, theme, density, data states, keyboard flow, and production bundle.
 
@@ -44,11 +44,9 @@ These paths exist after installation and are the source of truth:
 | `node_modules/themelia-ui/docs/generated/components/INDEX.md` | module-by-module API references and recipes |
 | `node_modules/themelia-ui/docs/generated/component-index.json` | machine-readable discovery records |
 | `node_modules/themelia-ui/docs/generated/public-api.md` | every exported name and exact subpath |
-| `node_modules/themelia-ui/docs/generated/imports.md` | every JS/CSS import and optional-peer owner |
+| `node_modules/themelia-ui/docs/generated/imports.md` | every import and optional-peer owner |
 | `node_modules/themelia-ui/docs/generated/recipes.json` | machine-readable live-preview examples |
-| `node_modules/themelia-ui/src/styles/TOKENS.md` | exhaustive public theme-author contract |
-| `node_modules/themelia-ui/src/styles/FACTORS.md` | scale, spacing, density, and typography factors |
-| `node_modules/themelia-ui/src/styles/SCOPES.md` | boundaries where derived tokens recompute |
+| `node_modules/themelia-ui/src/styles/TOKENS.md` | the theme contract: every variable, its role, and what components compute from it |
 | `node_modules/themelia-ui/docs/generated/migration.md` | every renamed or removed name, token and utility, with what replaces it |
 | `node_modules/themelia-ui/scripts/consumer/codemod.mjs` | applies the mechanical half of an upgrade to your source |
 
@@ -67,11 +65,11 @@ node node_modules/themelia-ui/scripts/consumer/find-component.mjs --peer=@tansta
 node node_modules/themelia-ui/scripts/consumer/find-component.mjs --help
 ```
 
-It indexes 97 modules, 386 attributed live recipes, and
-118 live preview routes by public symbol, module id, recipe title, preview route,
+It indexes 97 modules, 395 attributed live recipes, and
+119 live preview routes by public symbol, module id, recipe title, preview route,
 component capabilities, descriptions, and positive selection guidance. Negative `avoidWhen` guidance is never treated as a
 recommendation. `--json` includes the exact
-`publicImport`, `cssImport`, `apiDoc`, optional peers, dependencies, and alternatives.
+`publicImport`, `apiDoc`, optional peers, dependencies, and alternatives.
 Use `--explain` to see matched components and why they fit. Component guidance identifies
 curated decisions separately from module-level fallback; missing prop defaults are not inferred.
 <!-- /GENERATED:search -->
@@ -102,9 +100,9 @@ Selection rules:
 | Base (`base`) | 54 | one generic concept: text roles, controls, rows, passive structure | `themelia-ui/base/accordion` |
 | Layout (`layout`) | 9 | page and application shells | `themelia-ui/layout/app-shell` |
 | Features (`features`) | 24 | an owned interaction lifecycle — a context, a hook, a state machine | `themelia-ui/features/actions` |
-| Blocks (`blocks`) | 5 | an arrangement rendering a subject; the admin blocks make up the admin profile | `themelia-ui/admin/patterns/access` |
+| Blocks (`blocks`) | 5 | an arrangement rendering a subject; the admin blocks make up the admin profile | `themelia-ui/blocks/admin/access` |
 
-97 modules, 752 public components, 1070 exported symbols in total.
+97 modules, 752 public components, 1072 exported symbols in total.
 <!-- /GENERATED:tiers -->
 
 Dependencies flow downward:
@@ -152,21 +150,21 @@ leaflet. Reach for a module by its own subpath and the question never comes up.
 <!-- GENERATED:delivery by scripts/gen-agent-skill.mjs — do not edit between these markers. -->
 ```tsx compile
 import { Button } from "themelia-ui/base/buttons"
-import "themelia-ui/base/buttons.css"
 ```
 
-**The JavaScript imports no CSS.** A component whose module stylesheet is not imported
-renders unstyled.
+**A component brings its own CSS.** In a bundled app (Vite, webpack, Rspack, Next.js, React
+Router, Astro) importing the component is enough: its stylesheet arrives with its
+JavaScript, once, and a module the application never imports brings none. Do not also
+import `themelia-ui/style.css` or a module stylesheet from JavaScript; that loads the CSS twice.
 
-**The stylesheet is split per module.** 90 of 97 modules ship one; a module whose components draw nothing has none. Each module stylesheet imports
-`core.css` itself, so the tokens, themes, and cascade layer order arrive automatically.
-Import `core.css` on its own only when application CSS needs the token contract before
-any component stylesheet is loaded.
+**Server rendering with Vite needs one line.** Astro, React Router, TanStack Start and Vike
+list `themelia-ui` in `ssr.noExternal`; Astro renders the kit unstyled without it.
 
-`themelia-ui/style.css` is the deduplicated union of every sheet, for a consumer who would
-rather not track them. It is larger than what any one application uses.
+**No bundler:** link `themelia-ui/style.css`, which includes `core.css`. Node, Vitest and
+`require()` load the JavaScript with no CSS setup; Jest needs 29.4 or newer, with the package
+exempted in `transformIgnorePatterns`.
 
-Import consumer overrides after the kit. Its component rules are layered, so ordinary
+Consumer overrides need no ordering: the kit's component rules are layered, so ordinary
 unlayered app CSS wins without specificity tricks.
 <!-- /GENERATED:delivery -->
 
@@ -192,7 +190,7 @@ There are 15 optional peer packages. A consumer only needs the peers reachable f
 | `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` |
 <!-- /GENERATED:peers -->
 
 ## Provider, scopes, themes, and portals
@@ -224,15 +222,15 @@ export function ScopedPreview() {
 }
 ```
 
-Theme through the public contract in `node_modules/themelia-ui/src/styles/TOKENS.md`.
-The three factors are `--scale` (everything), `--density-scale` (spacing and control
-geometry, rounded to whole pixels) and `--text-scale` (type); the last two default to
-`--scale`. Set them on `:root`, with a `density` preset, or on a scope boundary; semantic
-colours are re-derived at each boundary, so override those through the provider or a scope. Component-level variables
-are implementation plumbing unless the public token reference explicitly promotes them.
+Theme through the public contract in `node_modules/themelia-ui/src/styles/TOKENS.md`: about
+eighty variables, declared once at `:root`, each colour a `light-dark(light, dark)` pair. Set
+the ones you change on `:root` (or on any element, for a region); nothing below `:root`
+declares them again. A denser region is the provider's `density` or `scale`, and type alone
+is `typography.scale`. A component's own variables are private (`--_x`), never an override
+surface.
 
-Import application overrides after kit CSS. Kit component rules are layered, so ordinary
-unlayered consumer CSS wins without `!important`. Target stable documented `data-slot` or
+Kit component rules are layered, so ordinary unlayered consumer CSS wins whatever its order,
+without `!important`. Target stable documented `data-slot` or
 BEM hooks, and Base UI's state attributes (`data-open`, `data-checked`, `data-disabled`,
 `data-highlighted`, `data-popup-open`) for a state — not Radix's `[data-state="open"]`; never
 target CSS Module hashes. If the application uses Tailwind

package/.agents/skills/themelia-ui/references/api-compatibility.md

@@ -15,9 +15,9 @@ exported props/type members are compatibility surfaces. Public global theme toke
 | a documented default changes | behavioural change; release notes required |
 | component token or hashed CSS Module name changes | internal unless documented as an extension point |
 
-A deprecated API introduced during a stable major remains available for that major with a
-named replacement and migration instructions. It is removed only in the next major unless
-security or correctness makes retaining it unsafe.
+3.1 removes obsolete aliases and adapters. Removed names do not stay available solely for an
+upgrade window. A breaking release records the replacement in the migration reference and
+the changelog; consumers pin the old version until they are ready to update.
 
 A removal, a newly required member or an incompatible type change ships with a migration
 record: the migration reference (`node_modules/themelia-ui/docs/generated/migration.md`) names each one with its

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

@@ -68,11 +68,8 @@ generic metadata, and an action without teaching the package what an invoice is:
 
 ```tsx compile
 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"
 
 type Invoice = { id: string; number: string; customerName: string; status: string; dueLabel: string }
 export function InvoiceDetail({ invoice, onCollectPayment }: {
@@ -111,10 +108,8 @@ callbacks, then open each linked module reference for the complete prop contract
 ### Dashboard
 
 ```tsx fragment — dashboard data and chart series come from the consuming application
-import { MetricGrid } from "themelia-ui/patterns/analytics"
-import "themelia-ui/patterns/analytics.css"
+import { MetricGrid } from "themelia-ui/blocks/analytics"
 import { Page } from "themelia-ui/layout/page"
-import "themelia-ui/layout/page.css"
 
 <Page header={{ title: "Overview", description: periodLabel }}>
   <MetricGrid metrics={metrics} variant="card" />
@@ -128,7 +123,6 @@ window, permission-filtered figures, and what clicking a metric means.
 
 ```tsx fragment — columns, filters, records, paging, and mutations are consumer-owned
 import { DataView, DataViewPagination } from "themelia-ui/features/data-view"
-import "themelia-ui/features/data-view.css"
 
 <DataView
   data={records}
@@ -152,9 +146,7 @@ record type out of the package.
 
 ```tsx fragment — validation, field values, submit mutation, and product copy remain in the app
 import { FormActionsBar, FormField, FormSection, SubmitStateButton } from "themelia-ui/base/forms"
-import "themelia-ui/base/forms.css"
 import { Input } from "themelia-ui/base/text-inputs"
-import "themelia-ui/base/text-inputs.css"
 
 <FormSection title="Billing" description="Where invoices go.">
   <FormField label="Company" error={errors.company}>
@@ -171,7 +163,6 @@ adapter when React Hook Form already owns the state.
 
 ```tsx fragment — route matching and the router link renderer belong to the application
 import { AsideNavShell } from "themelia-ui/layout/settings"
-import "themelia-ui/layout/settings.css"
 
 <AsideNavShell
   title="Settings"
@@ -218,15 +209,10 @@ the entered value; pending state prevents a second submission.
 ```tsx compile
 import { useState } from "react"
 import { Card, CardHeader, CardContent } from "themelia-ui/base/cards"
-import "themelia-ui/base/cards.css"
 import { FormField } from "themelia-ui/base/forms"
-import "themelia-ui/base/forms.css"
 import { Input } from "themelia-ui/base/text-inputs"
-import "themelia-ui/base/text-inputs.css"
 import { Button } from "themelia-ui/base/buttons"
-import "themelia-ui/base/buttons.css"
 import { Stack } from "themelia-ui/base/structure"
-import "themelia-ui/base/structure.css"
 
 export function RenameRecord({ initialName, save }: {
   initialName: string
@@ -248,7 +234,7 @@ export function RenameRecord({ initialName, save }: {
         catch { setError("Could not save. Your changes are still here; try again.") }
         finally { setPending(false) }
       }}>
-        <Stack gap="md">
+        <Stack gap="sm">
           <FormField label="Name" error={error}>
             <Input value={name} disabled={pending} onChange={(event) => setName(event.target.value)} />
           </FormField>
@@ -270,7 +256,6 @@ filtering contract to your query layer instead of filtering an already paged sub
 ```tsx compile
 import { useState } from "react"
 import { DataView, type DataViewProps } from "themelia-ui/features/data-view"
-import "themelia-ui/features/data-view.css"
 import { FilterType, FilterOperator, type ActiveFilter, type FilterConfig } from "themelia-ui/features/filters"
 
 type RecordRow = { id: string; name: string; status: string }
@@ -298,7 +283,6 @@ edge fade through the public prop instead of adding a local mask or a second scr
 
 ```tsx compile
 import { Tabs, TabList, Tab, TabPanel } from "themelia-ui/base/navigation"
-import "themelia-ui/base/navigation.css"
 
 export function SettingsTabs() {
   return <Tabs defaultValue="general">

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

@@ -73,14 +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
-
-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).
+## Vite, Next.js, and 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/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
+docs/learn/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

@@ -9,11 +9,13 @@ 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
 
@@ -36,41 +38,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`,