themelia-ui 1.0.0

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

@@ -0,0 +1,76 @@
+# Forms
+
+The kit does not own your form state. It defines a one-method interface that any form library
+can satisfy, and binds its fields to whatever satisfies it.
+
+```ts fragment — shape only, not a program
+interface FormControl<TValues> {
+  useField<TValue>(name: string): FieldState<TValue>
+}
+```
+
+That is the whole contract. `FieldState` is `{ value, setValue, onBlur?, error?, disabled? }`
+— everything past the first two is optional.
+
+## Plain React state
+
+```tsx compile
+import { FormField } from "themelia-ui/base/forms"
+import { Input } from "themelia-ui/base/text-inputs"
+import { useFormFieldBinding, useStateFormControl } from "themelia-ui/forms"
+
+const control = useStateFormControl({ email: "", workspace: "acme-corp" })
+
+function BoundInput({ name, label, control }) {
+  const field = useFormFieldBinding<string>({ name, control })
+  return (
+    <FormField label={label} error={field.error}>
+      <Input
+        value={field.value ?? ""}
+        onChange={(event) => field.onValueChange(event.target.value)}
+        onBlur={field.onBlur}
+      />
+    </FormField>
+  )
+}
+```
+
+`useStateFormControl` also exposes `values` and `reset`, which a library-backed control owns
+itself.
+
+## React Hook Form
+
+```tsx compile
+import { rhfFormControl } from "themelia-ui/forms-rhf"
+
+const form = useForm({ defaultValues: { email: "" } })
+const control = rhfFormControl(form.control)
+```
+
+It delegates to `useController`, so registration, validation and dirty tracking keep working
+— it adds a shape, not a second source of truth.
+
+The adapter lives behind its own subpath so `themelia-ui/forms` stays dependency-free. A
+consumer on plain state never resolves react-hook-form, which is what makes it a genuinely
+optional peer.
+
+## 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
+`aria-describedby` at the supporting line, and sets `aria-invalid` on the control when there
+is an error — filling gaps rather than overriding a caller who set any of them explicitly.
+Errors are announced `aria-live="polite"`, so validation firing on each keystroke does not
+interrupt typing.
+
+`FieldGroup` covers several controls sharing one label and one supporting line — a date
+range, a name split in two.
+
+## Generated forms
+
+When the fields come from a schema at runtime rather than being written by hand, use
+`features/schema-form`. When they are known at build time, write them: a schema adds
+indirection that only pays for itself when the shape is genuinely dynamic.
+
+Live examples: `/form-binding`, `/form-field`, `/form-workflow`, `/schema-form`.

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

@@ -0,0 +1,78 @@
+# Framework and application wiring
+
+The package owns presentation and reusable interaction state. The consuming application
+owns routing, server data, mutations, permissions, analytics, persistence, and the i18n
+runtime. Those concerns meet through explicit props rather than hidden framework imports.
+
+## 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.
+
+```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.
+
+## 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
+async lifecycle; the application decides cache invalidation, retries, and error reporting.
+
+```tsx fragment — query client and mutation implementation belong to the application
+<ResourceList
+  items={query.data ?? []}
+  loading={query.isPending}
+  error={query.error?.message}
+  onRetry={() => query.refetch()}
+  onItemAction={(item, action) => mutations.run(action, item.id)}
+/>
+```
+
+## Permissions
+
+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.
+
+## Translation
+
+Supply user-facing package copy through each component's `strings` prop. 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 families freely. Interactive families carry their own
+`"use client"` boundary in the published entrypoint. Avoid creating a single client wrapper
+around the entire package: exact subpaths keep server-pure imports server-pure and optional
+peers isolated.
+
+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 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.
+
+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
+a light/dark flash or hydration disagreement.
+
+## Persistence
+
+Controlled values belong in application state. Persist after the package calls the change
+callback, then feed the resulting value back. Optimistic updates, rollback, offline queues,
+and URL synchronization remain application policy.
+
+This boundary is what makes business-specific composition safe: the package supplies stable
+visual and interaction contracts without knowing the consumer's framework or domain model.

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

@@ -0,0 +1,109 @@
+# Localization
+
+The kit ships English defaults and no translation machinery. Every string it owns is
+overridable, and nothing in it inspects `navigator.language` or imports a translator.
+
+## Strings
+
+Each family exports a `*Strings` interface and a `default*Strings` object, and takes a
+`strings` prop:
+
+```tsx fragment — shape only, not a program
+<Copyable strings={{ copy: "Kopieren", copied: "Kopiert" }} value={apiKey} />
+```
+
+Overrides are **deep-merged**, one key at a time. A nested dictionary can be overridden
+partially without restating its siblings:
+
+```tsx fragment — a template with a hole in it
+<Comments strings={{ composer: { placeholder: "Schreiben…" } }} />
+```
+
+That matters more than it looks. Many families nest their copy, and a shallow merge would
+silently drop every sibling key of the one you set, leaving an interface half translated.
+Partial overrides preserve every sibling default.
+
+### A sentence is one key, not several
+
+Copy with a value in it is a **function**, not a template assembled at the call site:
+
+```ts fragment — shape only, not a program
+remove: (name: string) => `Remove ${name}`
+position: (name: string, index: number, total: number) =>
+  `${name}, position ${index} of ${total}. Use the arrow keys to reorder.`
+```
+
+Word order, the word between the parts, and the plural form are all part of the sentence,
+and none of them is English's to fix. `${strings.remove} ${file.name}` looks translated and
+is not: the space and the order are still hardcoded, and several languages need neither.
+
+The same reason applies to plurals. `count === 1 ? "person" : "people"` is an English rule
+written into a component; most languages have more than two forms, so the whole function has
+to be replaceable rather than the two words inside it.
+
+### What consumers can rely on
+
+- Component-owned visible and accessible copy belongs to the family'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.
+- Exported `default*Strings` objects provide the complete shape for a locale adapter.
+- Decorative `alt=""` remains valid and should not be replaced with spoken copy.
+- Sentence functions own word order and plural decisions. Consumers should replace the
+  function rather than concatenate translated fragments around a runtime value.
+
+## Formatting
+
+Locale and formatting policy live in the provider, not in each component:
+
+```tsx fragment — shape only, not a program
+<UIRoot config={{ formatting: { locale: "de-DE" }, money: { defaultCurrency: "EUR" } }}>
+```
+
+The display primitives — `Money`, `Date`, `DateTime`, `FileSize`, `Number` — read it. A
+component takes a prop first, then the provider, then its own fallback, so a one-off stays a
+one-off.
+
+### Dates need two things, and they are separate
+
+```tsx fragment — shape only, not a program
+import { de } from "date-fns/locale"
+
+<UIRoot config={{
+  formatting: { locale: "de-DE" },        // Intl: numbers, money, relative time
+  dates: {
+    locale: de,                            // date-fns: month and weekday NAMES
+    weekStartsOn: 1,                       // which column a calendar begins in
+    format: "dd.MM.yyyy",
+    timeFormat: "HH:mm",                   // "p" follows the locale's own convention
+  },
+}}>
+```
+
+`dates.locale` cannot be derived from `formatting.locale`: date-fns locales are modules, and
+importing all of them to look one up by tag would put every language in every bundle. The
+consumer imports the one it needs.
+
+### Range presets
+
+`createRangePresets` builds the shortcuts a reporting picker offers, in your language and on
+your week:
+
+```ts fragment — shape only, not a program
+const presets = createRangePresets({
+  strings: { thisWeek: "Diese Woche" },
+  weekStartsOn: 1,
+})
+```
+
+The exported `RANGE_PRESETS` constant is English and uses date-fns's own week start, which
+is Sunday — while the provider's default is Monday. So "This week" selected Sunday to
+Saturday beside a calendar drawn Monday to Sunday. A constant cannot read a provider; use
+the factory when either the language or the week matters. `RANGE_PRESETS` is deprecated and
+removal targets 2.0.
+
+## Right-to-left
+
+`DirectionProvider` from `base/direction` sets direction for a subtree when the document
+itself is not RTL. When the whole document is, the `dir` attribute on `<html>` is enough and
+the provider is unnecessary.

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

@@ -0,0 +1,142 @@
+<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
+
+# 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.
+
+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.
+
+## general profile — 96 families
+
+| 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` | — |
+| `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` | — |
+| `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` | — |
+| `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/suggestions` | `themelia-ui/features/suggestions` | `themelia-ui/features/suggestions.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` | — | — |
+
+## admin profile — 2 families
+
+| 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` | — |
+
+## 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.
+
+| peer | reachable from |
+| --- | --- |
+| `@dnd-kit/core` | `features/kanban` |
+| `@dnd-kit/sortable` | `features/kanban` |
+| `@dnd-kit/utilities` | `features/kanban` |
+| `@tanstack/react-table` | `features/data-view`, `features/products`, `features/table` |
+| `@tiptap/core` | `features/rich-text-editor/tiptap` |
+| `@tiptap/pm` | `features/rich-text-editor/tiptap` |
+| `@tiptap/starter-kit` | `features/rich-text-editor/tiptap` |
+| `leaflet` | `features/map` |
+| `leaflet-draw` | `features/map` |
+| `leaflet.fullscreen` | `features/map` |
+| `leaflet.markercluster` | `features/map` |
+| `react-hook-form` | `features/sync`, `forms-rhf` |
+| `react-leaflet` | `features/map` |
+| `react-leaflet-markercluster` | `features/map` |
+| `recharts` | `base/chart`, `patterns/analytics` |

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

@@ -0,0 +1,82 @@
+# Installation
+
+```bash
+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).
+
+## 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 makes every consumer's bundle the
+union of every family, and makes an optional peer reachable from an import that did not ask
+for it.
+
+```tsx compile
+import { Button } from "themelia-ui/base/buttons"
+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
+prototyping. Shipping code should name subpaths — that is what keeps the JS and the CSS to
+what you actually used.
+
+The exact import for every family is in
+[`docs/generated/imports.md`](imports.md), generated from the package manifest.
+
+## CSS
+
+Styles are not injected by the JavaScript. Import each family's stylesheet beside its
+components. Family stylesheets are self-contained: each imports the shared tokens, themes,
+and cascade layer order from `core.css` for you.
+
+```tsx fragment — shape only, not a program
+import "themelia-ui/base/buttons.css"
+```
+
+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.
+
+A family whose components draw nothing has no sheet. `imports.md` records which.
+
+If you would rather not track sheets per family, `themelia-ui/style.css` is the
+deduplicated union of all of them. It is larger than what any one app uses.
+
+Import application overrides after the kit. Component rules live in cascade layers, so
+ordinary unlayered consumer CSS wins without specificity tricks; stable `data-slot`,
+`data-state`, and BEM hooks provide the selectors.
+
+## Optional peers
+
+Every peer other than React is optional, and each is reachable only from the families that
+use it — so a consumer who never imports `features/map` never resolves Leaflet.
+
+The peer-to-family table is generated into
+[`docs/generated/imports.md`](imports.md), not restated here. The hand-written
+version of it in this file was wrong within an hour: it missed one family under
+`@tanstack/react-table` and claimed `react-hook-form` was reachable only from `forms-rhf`,
+when `features/sync` uses it too.
+
+`react-hook-form` is still the clearest illustration of the rule. The adapter is one function
+and lives behind its own subpath so `themelia-ui/forms` stays dependency-free — a
+consumer on plain React state never resolves react-hook-form at all, which is what makes it
+optional in fact rather than in name. See [Forms](forms.md).
+
+Release verification fails when a family reaches an optional peer it does not declare, so
+the generated table is checked against the package graph rather than maintained by hand.
+
+## Profiles
+
+The package ships two profiles from one install:
+
+- **General** — typography, formatted primitives, controls, generic patterns, layout shells
+  and domain-neutral interaction features.
+- **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`). The direction is enforced: an admin
+family may build on a general one, never the reverse.

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

@@ -0,0 +1,57 @@
+# Compatibility and migration
+
+The package is `1.0.0`. The stable-major policy below applies to consumers of 1.x.
+
+## Before 1.0
+
+Before the stable release, a breaking change had to arrive with a codemod or mechanical
+migration instructions. "Mechanical" means a consumer can apply it by search and replace or
+by running a script—not by re-reading their code and deciding.
+
+Every change is classified as one of:
+
+- **additive** — a new export, a new optional prop
+- **documentation-only** — no runtime or type change
+- **behaviour-preserving internal** — a refactor whose observable behaviour is identical
+- **deprecation** — the old name still works, and says what replaces it
+- **breaking** — anything else
+
+## During 1.x
+
+An alias introduced during a stable major is deprecated in that major, documented with its
+replacement, and removed only in the next one. It stays for one full stable major unless
+security or correctness makes keeping it unsafe.
+
+`1.0.0` is the first release that claims the improvement plan is complete. Releases before it
+may ship completed phases; the README names which profile and migration contracts are stable
+at any given point.
+
+## Import paths
+
+Layer barrels — `themelia-ui/base` and its siblings — are not public and will not
+become public. One specifier pulling an entire layer also pulls every optional peer inside
+it, which is the opposite of what the exact-subpath shape is for.
+
+If you are migrating from a broad import, the mapping from old specifier to exact subpath is
+generated into
+`docs/generated/migration-broad-imports.md` (`node_modules/themelia-ui/docs/generated/migration-broad-imports.md`).
+
+## What is not a compatibility surface
+
+Two things get mistaken for one:
+
+- **Component tokens.** Component-level custom properties are plumbing. They are
+  renamed and removed freely. The 166 contract names in
+  `src/styles/TOKENS.md` (`node_modules/themelia-ui/src/styles/TOKENS.md`) are the contract.
+- **CSS class names.** CSS Modules hashes them. The stable DOM hooks are the
+  `{kebab-name}--component` classes and the `data-slot` attributes, which are contract.
+
+## Verifying an upgrade
+
+After changing versions, type-check and build the consuming application against the installed
+package rather than a source alias. Run its unit, interaction, accessibility, and production
+bundle checks, then exercise the adopted families across the app's themes and density modes.
+
+The focused matrix is in [Verifying a consuming application](verification.md). Package
+maintainers separately bind release evidence to the exact clean commit, but consumers should
+not need this repository's scripts or source tree to validate an upgrade.