themelia-ui 2.0.1 → 3.0.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 and exact module stylesheet.
 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,7 +41,7 @@ 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 |
@@ -52,7 +52,7 @@ These paths exist after installation and are the source of truth:
 | `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 +60,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, 386 attributed live recipes, and
+118 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.
 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,63 +92,61 @@ 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/admin/patterns/access` |
+
+97 modules, 752 public components, 1070 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. -->
@@ -157,7 +155,10 @@ 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
+**The JavaScript imports no CSS.** A component whose module stylesheet is not imported
+renders unstyled.
+
+**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.
@@ -169,11 +170,11 @@ Import consumer overrides after the kit. Its component rules are layered, so ord
 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 |
 | --- | --- |
@@ -259,15 +260,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 +278,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

@@ -19,19 +19,19 @@ A deprecated API introduced during a stable major remains available for that maj
 named replacement and migration instructions. It is removed only in the next major unless
 security or correctness makes retaining it unsafe.
 
-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
 
@@ -105,7 +106,7 @@ 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
 
@@ -120,7 +121,7 @@ import "themelia-ui/layout/page.css"
 </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
@@ -261,7 +262,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.
@@ -317,22 +318,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 +342,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
+```

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

@@ -6,21 +6,35 @@ runtime. Those concerns meet through explicit props rather than hidden framework
 
 ## Routing
 
-Pass the router's link through `render` or a family's documented `renderLink` adapter. Do
-not put navigation in an `onClick` when the destination is a URL: a real link preserves
-open-in-new-tab, the status-bar destination, and browser semantics.
+Pass the router's link through `render`, or through `renderLink` where a component renders
+links of its own. Do not put navigation in an `onClick` when the destination is a URL: a
+real link preserves open-in-new-tab, the status-bar destination, and browser semantics.
 
 ```tsx fragment — replace AppLink with the link component from the consuming router
 <Button render={<AppLink to="/invoices/new" />}>New invoice</Button>
 ```
 
-Layout navigation adapters accept the same idea at the page or shell boundary. The kit does
-not import React Router, Next.js, Remix, or another router.
+Every `renderLink` takes the same function, a `LinkRenderer`: the sidebar and header, page
+headers and actions, menus and action buttons, navigation tabs, pagination, and table
+cells. Write it once:
+
+```tsx fragment — replace AppLink with the link component from the consuming router
+import type { LinkRenderer } from "themelia-ui/layout/sidebar"
+
+export const renderLink: LinkRenderer = ({ href, children, active, disabled, external, ...rest }) =>
+  disabled || !href ? <span {...rest}>{children}</span> : <AppLink to={href} {...rest}>{children}</AppLink>
+```
+
+Return one element and spread the rest of the props onto it: they carry the class, the
+`aria-current` of the current page and the click handler the component needs. `active`,
+`disabled` and `external` are hints to read. `Pagination` builds its addresses with
+`pageHref={(page) => ...}` and then renders them through the same `renderLink`. The kit
+does not import React Router, Next.js, Remix, or another router.
 
 ## Queries and mutations
 
 Fetch records outside the component, pass data and loading/error state in, and connect
-mutations through callbacks. A callback may return a promise when the family documents an
+mutations through callbacks. A callback may return a promise when the module documents an
 async lifecycle; the application decides cache invalidation, retries, and error reporting.
 
 ```tsx fragment — query client and mutation implementation belong to the application
@@ -40,7 +54,7 @@ async lifecycle; the application decides cache invalidation, retries, and error
 
 Resolve authorization before constructing actions. Omit an action the user cannot perform;
 disable it only when seeing the unavailable action is itself useful and provide the reason
-through the family's tooltip or description seam.
+through the module's tooltip or description seam.
 
 ## Translation
 
@@ -50,7 +64,7 @@ from the complete shape rather than guessing keys; see [Internationalization](i1
 
 ## Server rendering and client boundaries
 
-Import server-pure formatting families freely. Interactive families carry their own
+Import server-pure formatting modules freely. Interactive modules carry their own
 `"use client"` boundary in the published entrypoint. Do not wrap the whole package in one
 client module: exact subpaths keep server-pure imports server-pure and optional peers
 isolated.
@@ -61,11 +75,12 @@ 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.
+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).
 
 Server-rendered HTML and the client bundle must load the same theme tokens before hydration.
 Apply the theme attribute and provider configuration from the same persisted value to avoid

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

@@ -5,8 +5,8 @@ overridable, and nothing in it inspects `navigator.language` or imports a transl
 
 ## Strings
 
-Each family exports a `*Strings` interface and a `default*Strings` object, and takes a
-`strings` prop:
+Each module exports a `*Strings` interface and a `default*Strings` object, and its
+components take a `strings` prop:
 
 ```tsx fragment — shape only, not a program
 <Copyable strings={{ copy: "Kopieren", copied: "Kopiert" }} value={apiKey} />
@@ -19,7 +19,7 @@ partially, and every sibling key keeps its default:
 <DataTable strings={{ pagination: { previous: "Zurück", next: "Weiter" } }} />
 ```
 
-Where a family types its prop as `Partial<…Strings>`, TypeScript still asks for each nested
+Where a module types its prop as `Partial<…Strings>`, TypeScript still asks for each nested
 group whole; spread the group's default, for example
 `kind: { ...defaultTransactionStrings.kind, refund: "Rückerstattung" }`.
 
@@ -40,7 +40,7 @@ two forms. Replace the whole function, not the words inside it.
 
 ### What consumers can rely on
 
-- Component-owned visible and accessible copy belongs to the family's typed `strings`
+- Component-owned visible and accessible copy belongs to the module's typed `strings`
   contract, including placeholders, titles, alternative text, and announcements.
 - Product/domain copy still arrives through application data, children, or documented props;
   the package does not translate it or decide which message catalogue to use.

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

@@ -2,17 +2,16 @@
 
 # Exact imports
 
-Every family has one subpath. There are no layer barrels: `themelia-ui/base` and its three
-siblings were removed because one specifier pulled an entire layer and every optional peer
-inside it. The root carries the provider and the display primitives, both peer-free.
+Every module has one subpath. There are no tier barrels: `themelia-ui/base` and its three
+siblings do not exist, because one specifier would pull an entire tier and every optional
+peer inside it. The root carries the provider and the display primitives, both peer-free.
 
-Import the stylesheet column beside the exact JavaScript subpath. ESM bundlers also
-discover the family rules through the module graph, but the explicit form behaves the
-same in CJS and makes the selected CSS visible in application source.
+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.
 
-## general profile — 95 families
+## general profile — 95 modules
 
-| family | import | stylesheet | optional peers |
+| 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` | — |
@@ -110,17 +109,17 @@ same in CJS and makes the selected CSS visible in application source.
 | `theming` | `themelia-ui/theming` | — | — |
 | `ui-provider` | `themelia-ui/ui-provider` | — | — |
 
-## admin profile — 2 families
+## admin profile — 2 modules
 
-| family | import | stylesheet | optional peers |
+| 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` | — |
 
 ## Optional peers — 15 of them
 
-Each is reachable only from the families below, so a consumer who never imports one never
-resolves it. Release verification rejects a family that reaches an undeclared peer.
+Each is reachable only from the modules below, so a consumer who never imports one never
+resolves it. Release verification rejects a module that reaches an undeclared peer.
 
 | peer | reachable from |
 | --- | --- |