themelia-ui 2.0.1 → 3.1.0

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

@@ -8,19 +8,19 @@ description: Use when a React consumer is selecting, importing, composing, themi
 
 Use this skill for application code that consumes the package. It is not a maintainer guide.
 Do not infer APIs from source layouts or from shadcn conventions: this kit is Tailwind-free,
-uses CSS Modules over Base UI, publishes exact family subpaths, and has no `ui/` directory,
+uses CSS Modules over Base UI, publishes exact module subpaths, and has no `ui/` directory,
 `cn()` helper, `tailwind-merge`, or class-variance-authority contract.
 
 ## Workflow
 
 1. Search the packaged catalogue by the job the interface must do.
 2. Read the best match's `chooseWhen`, `avoidWhen`, alternatives, status, and optional peers.
-3. Open that family's generated API reference before writing JSX. It contains every public
+3. Open that module's generated API reference before writing JSX. It contains every public
    declaration, inherited prop contract, dependency, and attributed live-preview recipe.
-4. Prefer the highest ready family that owns the behavior, then customize it at the lowest
+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 family 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.
 
@@ -41,18 +41,16 @@ These paths exist after installation and are the source of truth:
 
 | authority | answers |
 | --- | --- |
-| `node_modules/themelia-ui/docs/generated/components/INDEX.md` | family-by-family API references and recipes |
+| `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 |
 
-## Find the right family
+## Find the right module
 
 <!-- GENERATED:search by scripts/gen-agent-skill.mjs — do not edit between these markers. -->
 Do not guess a component name, and do not fall back to a `<div>` because nothing obvious
@@ -60,31 +58,31 @@ came to mind. Ask:
 
 ```bash
 node node_modules/themelia-ui/scripts/consumer/find-component.mjs "key value facts"
-node node_modules/themelia-ui/scripts/consumer/find-component.mjs --layer=primitives --json
-node node_modules/themelia-ui/scripts/consumer/find-component.mjs --layer=base --limit=20
-node node_modules/themelia-ui/scripts/consumer/find-component.mjs --family=features/data-view
+node node_modules/themelia-ui/scripts/consumer/find-component.mjs --tier=primitives --json
+node node_modules/themelia-ui/scripts/consumer/find-component.mjs --tier=base --limit=20
+node node_modules/themelia-ui/scripts/consumer/find-component.mjs --module=features/data-view
 node node_modules/themelia-ui/scripts/consumer/find-component.mjs --peer=@tanstack/react-table
 node node_modules/themelia-ui/scripts/consumer/find-component.mjs --help
 ```
 
-It indexes 97 component families, 383 attributed live recipes, and
-118 live preview routes by public symbol, family 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 family-level fallback; missing prop defaults are not inferred.
+curated decisions separately from module-level fallback; missing prop defaults are not inferred.
 <!-- /GENERATED:search -->
 
 Selection rules:
 
 - Search first. Do not invent an export or recreate a package-looking local component.
 - Treat `avoidWhen` as a rejection signal, never as a keyword recommendation.
-- Choose the family whose public vocabulary owns the job. Use a lower layer only when the
+- Choose the module whose public vocabulary owns the job. Use a lower tier only when the
   application genuinely needs a new composition, not merely because its API is familiar.
-- If no family owns the need, semantic HTML or an application-owned composition is correct.
+- If no module owns the need, semantic HTML or an application-owned composition is correct.
   Preserve native semantics; do not wrap markup only to make it look package-like.
-- Never invent a prop such as `size="sm"`. Use a size prop only when that exact family's API
+- Never invent a prop such as `size="sm"`. Use a size prop only when that exact module's API
   documents it. Prefer global density and scale for system-wide geometry.
 - Use `Text`, `Heading`, `Label`, or `TextLink` when copy should follow a kit typography role.
   Choose the semantic element through the documented API; native text markup remains valid
@@ -92,88 +90,89 @@ Selection rules:
 - Follow the documented controlled or uncontrolled contract. Do not mix `value` with a
   default-only callback model, and do not hide server data or mutation policy inside a view.
 
-## Layer and composition model
+## Tiers and composition
 
-<!-- GENERATED:layers by scripts/gen-agent-skill.mjs — do not edit between these markers. -->
-| layer | families | what lives there | example import |
+<!-- GENERATED:tiers by scripts/gen-agent-skill.mjs — do not edit between these markers. -->
+| tier | modules | what lives there | example import |
 | --- | --- | --- | --- |
-| `typography` | 1 | text in a role — Text, Heading, Label, TextLink | `themelia-ui/base/typography` |
-| `primitives` | 1 | one formatted value, no interaction — Money, Date, Email | `themelia-ui/primitives` |
-| `base` | 53 | one generic concept: controls, rows, passive structure | `themelia-ui/base/accordion` |
-| `layout` | 9 | page and application shells | `themelia-ui/layout/app-shell` |
-| `features` | 24 | an owned interaction lifecycle — a context, a hook, a state machine | `themelia-ui/features/actions` |
-| `patterns` | 3 | an arrangement rendering a subject | `themelia-ui/patterns/analytics` |
-| `admin` | 2 | the admin profile, built only on general families | `themelia-ui/admin/patterns/access` |
-| `foundation` | 4 | the provider, the form contract, the root export | `themelia-ui/forms` |
-
-97 families, 752 public components, 1070 exported symbols in total.
-<!-- /GENERATED:layers -->
+| Foundations (`foundations`) | 4 | the provider, the form contract and the theming helpers | `themelia-ui/forms` |
+| Primitives (`primitives`) | 1 | one formatted value, no interaction — Money, Date, Email | `themelia-ui/primitives` |
+| 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/blocks/admin/access` |
+
+97 modules, 752 public components, 1072 exported symbols in total.
+<!-- /GENERATED:tiers -->
 
 Dependencies flow downward:
 
 ```text
-foundation → typography → primitives → base ─┬─ layout ────┐
-                                             ├─ features ──┼→ patterns → admin
-                                             └─────────────┘
+Foundations → base/typography → Primitives → Base ─┬─ Layout ────┐
+                                                   ├─ Features ──┼→ Blocks (general → admin)
+                                                   └─────────────┘
 ```
 
-`layout` and `features` are siblings. A pattern may compose either. The `admin` profile is
-terminal and may use general families; a general family never depends on an admin one.
+Layout and Features are siblings. A block may compose either. The `admin` profile is
+terminal and may use general modules; a general module never depends on an admin one.
 
-Use the layers by ownership, not by visual size:
+Use the tiers by ownership, not by visual size:
 
 - **Primitives** format one value without owning interaction.
 - **Base** owns a generic control or structural concept.
 - **Features** own a reusable interaction lifecycle, context, hook, or state machine.
 - **Layout** owns page and application structure without domain policy.
-- **Patterns** arrange lower layers around a subject.
-- **Admin** supplies terminal B2B/admin presentation vocabulary.
+- **Blocks** arrange lower tiers around a subject; the admin blocks supply terminal B2B/admin
+  presentation vocabulary.
 
 Application-specific cards, pages, workflows, and business components should normally be
-compositions of these families. The package owns reusable rendering and interaction
+compositions of these modules. The package owns reusable rendering and interaction
 mechanics. The application owns routing, fetching, caching, mutations, permissions,
 analytics, persistence, translation orchestration, and domain decisions. Pass those through
 documented props, callbacks, accessors, slots, render props, hooks, and provider seams.
 
 Read `references/composition.md` for page examples and
-`references/composition-ladder.md` for layer-by-layer tradeoffs.
+`references/composition-ladder.md` for tier-by-tier tradeoffs.
 
 ## Imports and CSS delivery
 
 <!-- GENERATED:root by scripts/gen-agent-skill.mjs — do not edit between these markers. -->
 **There are no broad aggregate barrels.** `themelia-ui/base` and
 `themelia-ui/features` are not published — an import of either fails to resolve.
-Every family has one exact subpath, which is what keeps an optional peer reachable only
-from the family that needs it.
+Every module has one exact subpath, which is what keeps an optional peer reachable only
+from the module that needs it.
 
 The root, `themelia-ui`, is the provider plus the primitives, and it is
 optional-peer-free: a consumer who imports it installs no recharts, no table, no
-leaflet. Reach for a family by its own subpath and the question never comes up.
+leaflet. Reach for a module by its own subpath and the question never comes up.
 <!-- /GENERATED:root -->
 
 <!-- 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 stylesheet is split per family.** 90 of 97 families ship one; a family whose components draw nothing has none. Each family 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.
+**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.
+
+**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 -->
 
-Never import an internal `src/` path or a nonexistent layer barrel. Install only the optional
+Never import an internal `src/` path or a nonexistent tier barrel. Install only the optional
 peers reachable from the exact families in use:
 
 <!-- GENERATED:peers by scripts/gen-agent-skill.mjs — do not edit between these markers. -->
-There are 15 optional peer packages. A consumer only needs the peers reachable from the exact family subpaths it imports; release verification checks that boundary.
+There are 15 optional peer packages. A consumer only needs the peers reachable from the exact module subpaths it imports; release verification checks that boundary.
 
 | peer | reachable only from |
 | --- | --- |
@@ -191,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
@@ -223,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
@@ -259,15 +258,14 @@ portals, strict CSP, or streaming SSR. Read `references/theming.md` before defin
 | file | open it when |
 | --- | --- |
 <!-- GENERATED:index-row by scripts/gen-agent-skill.mjs — do not edit between these markers. -->
-| `references/components/INDEX.json` | choosing a component. 97 families with `publicImport`, `publicSymbols`, and the `chooseWhen` / `avoidWhen` / `alternatives` that say which one to reach for. The machine surface — filter it, do not read it. |
+| `node_modules/themelia-ui/docs/generated/component-index.json` | choosing a component. 97 modules with `import`, `symbols`, and the `chooseWhen` / `avoidWhen` / `alternatives` that say which one to reach for. The machine surface: search it with `find-component.mjs` rather than reading it whole. |
 <!-- /GENERATED:index-row -->
-| `references/components/INDEX.md` | opening one complete generated family API reference |
 | `references/imports.md` | confirming exact imports and optional-peer ownership |
 | `references/installation.md` | installing the package and choosing CSS delivery |
 | `references/theming.md` | changing color, radius, density, scale, typography, DTCG, or Tailwind integration |
 | `references/provider-and-scoping.md` | configuring roots, nested regions, portals, CSP, or SSR |
 | `references/composition.md` | building application-specific pages and business components |
-| `references/composition-ladder.md` | choosing the highest ready layer and lowest extension seam |
+| `references/composition-ladder.md` | choosing the highest ready tier and lowest extension seam |
 | `references/framework-wiring.md` | connecting router, data, permissions, persistence, and rendering boundaries |
 | `references/forms.md` | binding fields to React state, react-hook-form, or another controller |
 | `references/i18n.md` | overriding component copy and translating application-owned text |
@@ -278,8 +276,8 @@ portals, strict CSP, or streaming SSR. Read `references/theming.md` before defin
 
 ## Consumer completion checklist
 
-- Exact family import and its CSS resolve from the installed package.
-- Only the selected families' optional peers are installed and bundled.
+- Exact module import and its CSS resolve from the installed package.
+- Only the selected modules' optional peers are installed and bundled.
 - Public props and slots are used; no internal path, hash class, or undocumented token leaks in.
 - Loading, empty, error, disabled, destructive, and largest-realistic data states are covered.
 - Keyboard traversal, focus return, names, descriptions, announcements, and contrast are sound.

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

@@ -15,23 +15,23 @@ 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.
 
-Every exported declaration is snapshotted, and a removal, a newly required member or an
-incompatible type change cannot ship without a migration record. ESM, CommonJS,
-declarations, CSS exports and exact subpaths are checked against the packed tarball.
+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
+replacement.
 
 ## What consumers should depend on
 
 Prefer the ready-made component, documented parts and hooks, the global theme contract,
 `data-slot`, BEM hooks, and the state attributes the primitives set (`data-open`,
 `data-checked`, `data-disabled`, `data-highlighted`, `data-popup-open`). Use `data-state`
-only where a family reference documents it; few families set it. Do not depend on source
+only where a module reference documents it; few modules set it. Do not depend on source
 paths, internal aliases, hashed CSS Module classes, undocumented DOM nesting, or
 component-owned custom properties.
 
-The generated [family references](components/INDEX.md) are the exact API
-inventory for the package version you installed. `CHANGELOG.md` records migrations and
-behavioural changes between versions.
+The generated module references (`node_modules/themelia-ui/docs/generated/components/INDEX.md`) are the exact API
+inventory for the package version you installed. The changelog (`node_modules/themelia-ui/CHANGELOG.md`) records
+migrations and behavioural changes between versions.

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

@@ -3,18 +3,18 @@
 # The composition ladder
 
 The [composition model](composition.md) lists eight rungs, from ordinary props to a
-documentation recipe. A family offers the *smallest sufficient* seam — not all eight, and
+documentation recipe. A module offers the *smallest sufficient* seam — not all eight, and
 not a headless hook where a prop would do.
 
 The rungs are ordinary props; controlled state and callbacks when state exists; accessors;
 named slots; render props; exported parts; headless hooks; and complete recipes. Passive
-families may stop at the first rung. Interaction features normally expose several.
+modules may stop at the first rung. Interaction features normally expose several.
 
-This table is derived from what each family declares, so it cannot describe a seam that
-was removed or miss one that was added. The table focuses on feature families, where the
+This table is derived from what each module declares, so it cannot describe a seam that
+was removed or miss one that was added. The table focuses on feature modules, where the
 higher rungs are meaningful; the columns start at accessors.
 
-| family | accessors | slots | render props | headless hook | partials | recipe |
+| module | accessors | slots | render props | headless hook | partials | recipe |
 | --- | :-: | :-: | :-: | :-: | :-: | :-: |
 | `features/actions` | ● | ● | · | ● | ● | ● |
 | `features/activities` | ● | ● | ● | ● | ● | ● |
@@ -38,7 +38,7 @@ higher rungs are meaningful; the columns start at accessors.
 | `features/rich-text-editor/tiptap` | · | · | · | · | · | · |
 | `features/schema-form` | ● | · | ● | ● | ● | ● |
 | `features/sync` | · | · | · | · | · | ● |
-| `features/table` | ● | ● | ● | ● | ● | ● |
+| `features/table` | ● | ● | · | ● | ● | ● |
 | `features/theme-tweaker` | · | ● | · | ● | ● | ● |
 
 ## The four the plan names

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

@@ -1,23 +1,24 @@
 # Composition model
 
 The kit is designed to build product-specific UI without copying library internals. Start
-at the highest layer that already owns the interaction, then compose downward only when the
+at the highest tier that already owns the interaction, then compose downward only when the
 ready-made surface does not express the job.
 
-## The layers
+## The tiers
 
-| layer | owns | consumer use |
+| tier | owns | consumer use |
 | --- | --- | --- |
-| typography | text roles | keep type, colour, truncation, and semantics consistent |
-| primitives | one formatted value | render money, dates, people, files, and other values |
-| base | one generic UI concept | controls, overlays, rows, cards, feedback, and structure |
-| layout | page and application shells | arrange routes without owning routing or data |
-| features | an interaction lifecycle | use controlled state, callbacks, accessors, parts, or hooks |
-| patterns | a subject-shaped arrangement | assemble base, layout, and feature families |
-| admin | terminal admin presentation | build on general families without leaking admin vocabulary down |
-
-`layout` and `features` are siblings. A pattern may compose both; neither may import a
-pattern. The complete generated graph is in Profiles (`node_modules/themelia-ui/docs/generated/profiles.md`).
+| Primitives | one formatted value | render money, dates, people, files, and other values |
+| Base | one generic UI concept | controls, overlays, rows, cards, feedback, and structure |
+| Base | text roles, in `base/typography` | keep type, colour, truncation, and semantics consistent |
+| Layout | page and application shells | arrange routes without owning routing or data |
+| Features | an interaction lifecycle | use controlled state, callbacks, accessors, parts, or hooks |
+| Blocks | a subject-shaped arrangement | assemble base, layout, and feature modules |
+| Blocks | terminal admin presentation, in the admin blocks | build on general modules without leaking admin vocabulary down |
+
+`base/typography` sits below Primitives. Layout and Features are siblings. A block may
+compose both; neither may import a block. The complete generated graph is in
+Profiles (`node_modules/themelia-ui/docs/generated/profiles.md`).
 
 ## The composition ladder
 
@@ -30,12 +31,12 @@ Use the lowest rung that solves the real requirement:
 5. Render props when a region needs the component's live state.
 6. Exported parts for assembling a different surface.
 7. A headless hook when the package presentation cannot express the design.
-8. A documented recipe that wires several families into a screen-level result.
+8. A documented recipe that wires several modules into a screen-level result.
 
-Not every family needs every rung. A passive Badge does not need controlled state; a feature
+Not every module needs every rung. A passive Badge does not need controlled state; a feature
 with an interaction lifecycle normally offers several. The generated
-[composition audit](composition-ladder.md) lists which seams each feature
-family exposes.
+[composition ladder](composition-ladder.md) lists which seams each feature
+module exposes.
 
 ## Build a business component
 
@@ -67,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 }: {
@@ -105,29 +103,26 @@ responsive geometry, tokens, and reusable interaction contracts.
 ## Common application compositions
 
 These are boundaries, not new package abstractions. Adapt the application-owned data and
-callbacks, then open each linked family reference for the complete prop contract.
+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" />
 </Page>
 ```
 
-The pattern owns metric presentation and responsive columns. The app owns the query, time
+The block owns metric presentation and responsive columns. The app owns the query, time
 window, permission-filtered figures, and what clicking a metric means.
 
 ### Resource index
 
 ```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}
@@ -151,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}>
@@ -170,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"
@@ -217,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
@@ -247,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>
@@ -261,7 +248,7 @@ export function RenameRecord({ initialName, save }: {
 
 ### Responsive resource filters
 
-Install the optional peers listed in the DataView family reference. The ready surface shares
+Install the optional peers listed in the DataView module reference. The ready surface shares
 one filter state across the desktop bar and mobile sheet; the application supplies records
 and owns fetching. This example filters local rows. For server filtering, wire the public
 filtering contract to your query layer instead of filtering an already paged subset twice.
@@ -269,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 }
@@ -297,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">
@@ -317,22 +302,22 @@ export function SettingsTabs() {
 
 | Situation | Composition rule |
 | --- | --- |
-| Initial loading | Use the family's loading contract where available; do not show a false empty result. |
+| Initial loading | Use the module's loading contract where available; do not show a false empty result. |
 | Refresh | Keep existing data and drafts visible where supported; distinguish refresh from first load. |
 | Empty or no matches | Distinguish an empty collection from filters excluding every result; offer the relevant next action. |
 | Error | Preserve user input, show recoverable feedback, and wire retry to the app's data operation. |
 | Pending mutation | Prevent duplicate actions; keep progress and errors associated with the initiating control. |
-| Narrow viewport | Use the family's mobile presentation (such as the filter sheet); keep state shared with desktop. |
+| Narrow viewport | Use the module's mobile presentation (such as the filter sheet); keep state shared with desktop. |
 | Typography/theme override | Let semantic owners inherit provider defaults; verify density changes spacing without demoting body copy. |
 
-Only use states the selected family exposes; the API reference is authoritative. The
+Only use states the selected module exposes; the API reference is authoritative. The
 complete examples above type-check against the built package, but their application
 callbacks are illustrative: verify persistence and browser behaviour in your app.
 
 ## When to wrap, compose, or contribute
 
-- **Wrap** when the product needs a stable local name or defaults around one family.
-- **Compose** when several public families form a product concept.
+- **Wrap** when the product needs a stable local name or defaults around one module.
+- **Compose** when several public modules form a product concept.
 - **Use parts or a hook** when a ready-made feature has the right lifecycle but the wrong
   presentation.
 - **Contribute to the package** only when the missing concept is domain-neutral, repeats in
@@ -341,5 +326,5 @@ callbacks are illustrative: verify persistence and browser behaviour in your app
   are not compatibility surfaces. Public props, exported parts, hooks, `data-slot`, BEM
   hooks, and global theme tokens are.
 
-Open [the family API index](components/INDEX.md) after choosing a family. It
-contains every public declaration and the live recipes attributed to that family.
+Open the module API index (`node_modules/themelia-ui/docs/generated/components/INDEX.md`) after choosing a module. It
+contains every public declaration and the live recipes attributed to that module.

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

@@ -86,5 +86,9 @@ When the fields come from a schema at runtime, use `features/schema-form`. When
 known at build time, write them: a schema adds indirection that only pays off when the shape
 is genuinely dynamic.
 
-Preview routes with recipes: `/form-binding`, `/form-field`, `/form-workflow`, `/schema-form`
-(search them with the finder's `--route=` option).
+The preview recipes for these patterns are on the routes `/form-binding`, `/form-field`,
+`/form-workflow` and `/schema-form`. The finder lists the modules behind one:
+
+```bash
+node node_modules/themelia-ui/scripts/consumer/find-component.mjs --route=/form-field
+```