themelia-ui 2.0.1 → 3.1.0

package/README.md

@@ -2,233 +2,230 @@
 
 **Foundations for every theme.**
 
-Themelia UI is a production-ready React component system built for applications that need
-more than a collection of isolated controls. It combines accessible components, composable
-features and layouts, and a compact CSS-variable contract that lets one theme control the
-whole interface.
-
-The package uses CSS Modules over [Base UI](https://base-ui.com) internally. It has no
-Tailwind dependency, but it provides a first-class Tailwind CSS v4 bridge for applications
-that use Tailwind. The result is a library that works with any styling stack while still
-giving Tailwind consumers token-aware utilities and predictable `className` overrides.
-
-- **Theme globally:** change colors, radius, spacing, density, type, motion, and elevation
-  through shared custom properties.
-- **Compose product UI:** build from formatted primitives, generic controls, interaction
-  features, layouts, and domain-neutral patterns without copying library source.
-- **Override locally:** use Tailwind utilities, ordinary CSS, stable BEM hooks, and documented
-  `data-*` states.
-- **Import narrowly:** every family has an exact JavaScript and CSS subpath; optional peers
-  stay outside applications that do not use them.
-- **Ship confidently:** accessibility, interaction, visual, token, package, SSR, CSP, and
-  consumer-fixture checks are part of the release gate.
+Themelia UI is a React component library for building applications: accessible controls,
+page layouts, interaction features and ready-made blocks, styled with precompiled CSS and
+themed through one set of CSS variables.
+
+- **One theme for the whole interface.** Colour, radius, spacing, density, type and motion
+  are CSS variables that every component reads, so one change reaches every component, in
+  light and dark.
+- **Plain CSS, nothing to configure.** Components are CSS Modules over
+  [Base UI](https://base-ui.com), shipped as precompiled stylesheets. No Tailwind, PostCSS or
+  plugin is needed; applications that use Tailwind CSS v4 get a bridge to the theme.
+- **Overrides without `!important`.** Component rules live in cascade layers, so a utility
+  in `className` or ordinary application CSS wins.
+- **Import only what you use.** Every module has its own subpath and brings only its own CSS.
+  Optional peers such as charts, maps and rich text are needed only by the modules that use
+  them.
+- **Your application keeps its policy.** Routing, data fetching, persistence, permissions and
+  translations stay in your code. Components take data, callbacks and render props.
 
 ## Contents
 
+- [Install](#install)
 - [Quick start](#quick-start)
-- [Choose how much CSS to load](#choose-how-much-css-to-load)
-- [Tailwind CSS v4](#tailwind-css-v4)
-- [Override without fighting the library](#override-without-fighting-the-library)
+- [Load the CSS](#load-the-css)
+- [Imports and tiers](#imports-and-tiers)
 - [Theming](#theming)
+- [Tailwind CSS v4](#tailwind-css-v4)
+- [Overrides](#overrides)
 - [Composition](#composition)
-- [Why CSS instead of Tailwind internally?](#why-css-instead-of-tailwind-internally)
-- [Imports and optional peers](#imports-and-optional-peers)
-- [Choose and discover components](#choose-and-discover-components)
+- [Find a component](#find-a-component)
 - [Documentation](#documentation)
+- [License](#license)
 
-## Quick start
-
-Install the package:
+## Install
 
 ```bash
 npm install themelia-ui
 ```
 
-React 19 and `react-dom` are required peer dependencies. Import the complete stylesheet for
-the simplest setup, put `UIProvider` at the application boundary, and use exact component
-subpaths:
+React 19 and `react-dom` are required peers. Every other peer is optional and needed only by
+the modules that use it; the [import table](https://unpkg.com/themelia-ui/docs/generated/imports.md) lists which.
+
+Themelia supports Chrome and Edge 125, Firefox 121 and Safari 17.5 or newer. Builds and
+server rendering need Node 20.19 or newer.
 
-```tsx compile
+## Quick start
+
+Put `UIProvider` at the root of the application and import each component from its module's
+subpath. In a bundled app, a component brings its own CSS:
+
+```tsx
 import { Button } from "themelia-ui/base/buttons"
 import { UIProvider } from "themelia-ui/ui-provider"
-import "themelia-ui/style.css"
 
 export function App() {
   return (
-    <UIProvider config={{ colorScheme: "system", density: "default" }}>
-      <Button tone="primary" buttonStyle="solid">
-        Save changes
-      </Button>
+    <UIProvider config={{ colorScheme: "system" }}>
+      <Button tone="primary">Save changes</Button>
     </UIProvider>
   )
 }
 ```
 
-The package owns presentation, accessible behavior, responsive geometry, and display
-defaults. Your application keeps routing, fetching, persistence, permissions, translations,
-and business state.
+Server rendering with Vite and pages with no bundler need one step more; see
+[Load the CSS](#load-the-css).
 
-## Choose how much CSS to load
+## Load the CSS
 
-Themelia never injects component styles from JavaScript. Choose one loading strategy and keep
-it consistent:
+The styles are precompiled CSS in cascade layers, declared in this order:
 
-| Strategy | Import | Use when |
-| --- | --- | --- |
-| Complete catalogue | `themelia-ui/style.css` | The application uses much of the library and values one root import. |
-| Family styles | `themelia-ui/<family>.css` | The application uses a smaller set and wants CSS to follow exact JS imports. |
-| Tokens only | `themelia-ui/core.css` | Application CSS needs the token contract before any component family is loaded. |
+```css
+@layer tokens, base, components, utilities;
+```
 
-For narrow loading, keep each family stylesheet beside its JavaScript import:
+**In a bundled app**, importing a component brings its stylesheet, once, and a module the
+application never imports brings none. Do not also import `style.css` or a module stylesheet
+from JavaScript; that loads the rules twice.
 
-```tsx compile
-import { Button } from "themelia-ui/base/buttons"
-import "themelia-ui/base/buttons.css"
-import { Page } from "themelia-ui/layout/page"
-import "themelia-ui/layout/page.css"
+**Server rendering with Vite** (Astro, React Router, TanStack Start, Vike) lists the package
+in `ssr.noExternal`, or Vite hands it to Node without its CSS:
 
-export function SavePage() {
-  return (
-    <Page header={{ title: "Workspace" }}>
-      <Button>Save</Button>
-    </Page>
-  )
-}
+```ts
+// vite.config.ts, or the vite key of astro.config.mjs
+export default { ssr: { noExternal: ["themelia-ui"] } }
 ```
 
-Every family stylesheet already imports `core.css`. Do not import both unless application
-CSS itself needs the tokens before the family stylesheet loads. The generated
-[import table](./docs/generated/imports.md) is the authority for every JavaScript path, CSS
-path, and optional peer.
+**Without a bundler**, link `themelia-ui/style.css`; it includes `core.css`:
 
-## Tailwind CSS v4
+| Stylesheet | Contains |
+| --- | --- |
+| `themelia-ui/core.css` | The theme variables, the layer order, the Geist typefaces and the base element styles. No component rules. |
+| `themelia-ui/style.css` | Everything: `core.css` and the rules of every module. |
 
-Themelia is **Tailwind-friendly, not Tailwind-dependent**. Tailwind remains excellent for
-application layout and one-off composition. Themelia keeps its component implementation in
-precompiled CSS so the package works in Vite, Next.js, Remix, an existing Tailwind app, or a
-project with no utility framework at all.
+### On the server and in tests
 
-### Install the bridge
+The package is ES modules. Outside a bundler its CSS imports resolve to an empty module, so
+Node loads it without the CSS: Vitest needs no configuration, CommonJS code on Node 20.19 or
+later can `require()` it, and a server render gets the CSS from the client build, or from
+Vite through `ssr.noExternal` as above. Jest needs 29.4 or newer and transforms nothing in
+`node_modules` by default: exempt the package in `transformIgnorePatterns`.
 
-In the CSS entry that loads Tailwind and the complete catalogue, use this order:
+## Imports and tiers
 
-```css
-@import "tailwindcss";
-@import "themelia-ui/style.css";
-@import "themelia-ui/tailwind.css";
-```
+Every module is published on its own subpath. Modules are grouped in tiers, from the theme
+up to complete blocks:
 
-If component styles are imported by family from TypeScript, use `core.css` in the CSS entry
-instead:
-
-```css
-@import "tailwindcss";
-@import "themelia-ui/core.css";
-@import "themelia-ui/tailwind.css";
+| Tier | Holds | Import from |
+| --- | --- | --- |
+| Foundations | The provider and scopes, theme helpers, form bindings and the theme stylesheet | `themelia-ui/ui-provider`, `themelia-ui/theming`, `themelia-ui/forms`, `themelia-ui/forms-rhf`, `themelia-ui/core.css` |
+| Primitives | One formatted value: money, dates, names, file sizes | `themelia-ui/primitives` |
+| Base | One control or concept, including `Text` and `Heading` | `themelia-ui/base/<module>` |
+| Layout | Page and application shells | `themelia-ui/layout/<module>` |
+| Features | An interaction lifecycle with controlled state | `themelia-ui/features/<module>` |
+| Blocks | Subject-shaped compositions of the tiers above | `themelia-ui/blocks/<module>`, `themelia-ui/blocks/admin/<module>` |
+
+```ts
+import { UIProvider } from "themelia-ui/ui-provider"
+import { Money } from "themelia-ui/primitives"
+import { Button } from "themelia-ui/base/buttons"
+import { Page } from "themelia-ui/layout/page"
+import { DataTable } from "themelia-ui/features/table"
+import { MetricGrid } from "themelia-ui/blocks/analytics"
 ```
 
-Then import each family stylesheet beside the component as shown above.
+There are no tier barrels: `themelia-ui/base` does not exist, so one import never pulls in a
+whole tier or an optional peer it did not ask for. The root, `themelia-ui`, exports the
+provider and the primitives, with no optional peers.
 
-The bridge is a generated Tailwind v4 theme declaration. It does two jobs:
-
-1. It exposes Themelia tokens as utilities: `bg-primary`, `text-muted-foreground`,
-   `rounded-sm` (the inner radius), `rounded-(--radius)` (the container radius), `p-md`,
-   and the rest resolve to the active Themelia theme, at the element.
-2. It prevents Tailwind defaults from silently replacing shared shadcn-shaped names such as
-   the radius, type, shadow, font, leading, easing, and animation variables.
+## Theming
 
-### Tailwind overrides work without `!important`
+Every component reads one set of CSS variables. Set them from React or from CSS.
 
-Themelia establishes an explicit cascade order:
+From React, `UIProvider` applies its configuration to everything inside it:
 
-```css
-@layer tokens, theming, base, components, utilities;
+```tsx
+<UIProvider
+  config={{
+    colorScheme: "system",   // "light", "dark" or "system"
+    density: "default",      // "compact", "default" or "comfortable"
+    theme: {
+      radius: "1rem",        // containers: cards, dialogs, popovers, menus
+      radiusSm: "0.5rem",    // items: controls, rows, chips, badges
+      colors: { primary: "oklch(0.55 0.19 250)" },
+    },
+  }}
+>
+  <App />
+</UIProvider>
 ```
 
-Its CSS Module rules compile into `components`; Tailwind classes compile into `utilities`.
-A declaration in a later layer wins regardless of selector specificity, so a utility passed
-through `className` overrides the component naturally. You do not need `!important`, a
-specificity hack, or `tailwind-merge`. Ordinary unlayered application CSS sits above every
-named layer when an app-level stylesheet needs the final say.
+A nested `UIProvider` themes one region, and inherits whatever it does not set. For finer
+control, `UIRoot`, `UIScope`, `Scope` and `UIPortalHost` each do one of its jobs; see
+[Provider and scoping](docs/learn/provider-and-scoping.md).
 
-Because every bridged utility reads `var(...)` at the element, it follows dark mode, nested
-providers, density scopes, and live theme changes:
+From CSS, set any theme variable on `:root`. A colour holds both modes as
+`light-dark(light, dark)`, and each element's `color-scheme` picks the half, so one
+declaration reaches every region, a dark region inside a light page included:
 
-```tsx compile
-import { Button } from "themelia-ui/base/buttons"
-import "themelia-ui/base/buttons.css"
-
-export function TailwindActions() {
-  return (
-    <div className="grid gap-lg sm:grid-cols-2">
-      <Button className="rounded-pill px-lg shadow-lg">Approve</Button>
-      <Button tone="neutral" className="justify-self-start">
-        Review later
-      </Button>
-    </div>
-  )
+```css
+:root {
+  --radius: 1rem;
+  --radius-sm: 0.5rem;
+  --primary: light-dark(oklch(0.55 0.19 250), oklch(0.72 0.14 250));
+  --primary-foreground: light-dark(oklch(0.985 0 0), oklch(0.2 0.03 250));
 }
 ```
 
-`rounded-pill`, `px-lg`, and `shadow-lg` use Themelia's live radius, spacing, and elevation
-values. Responsive layout utilities such as `sm:grid-cols-2` remain ordinary Tailwind.
+A colour given one value is used in both modes. Dark mode follows `class="dark"`,
+`data-theme="dark"` or, with `colorScheme: "system"`, the operating system's preference: each
+sets `color-scheme`, and nothing is declared twice.
 
-## Override without fighting the library
+Beyond a few variables:
 
-Use the narrowest override that matches the decision you are making.
+- `deriveThemePalette` from `themelia-ui/theming` derives a coherent palette from one
+  primary colour.
+- `ThemeTweaker` from `themelia-ui/features/theme-tweaker` lets people edit, preview and
+  export a theme while the application runs.
+- `themelia-ui/tokens.json` publishes the theme in the W3C design tokens format for design
+  tools.
 
-### 1. Change a product-wide decision with a variable
+[Theming](docs/learn/theming.md) covers each of these, and
+[`src/styles/TOKENS.md`](src/styles/TOKENS.md) names the variable for every role.
 
-Load application CSS after Themelia, then override the public contract. Raw inputs go on
-`:root`; semantic colours re-derive at every scope boundary, so declare them there:
+## Tailwind CSS v4
 
-```css
-:root {
-  --radius: 1rem;
-  --radius-sm: 0.5rem;
-  --scale: 0.95;      /* denser spacing and controls… */
-  --text-scale: 1;    /* …with type unchanged */
-}
+Themelia does not use Tailwind and does not need it. In an application that does, import
+the bridge in the CSS entry that loads Tailwind:
 
-:root, [data-ui-scope], [data-density], [data-theme], .light, .dark {
-  --primary: oklch(0.52 0.16 255);
-  --primary-foreground: oklch(0.985 0 0);
-}
+```css
+@import "tailwindcss";
+@import "themelia-ui/tailwind.css";
 ```
 
-Buttons, fields, menus, cards, overlays, layouts, and Tailwind bridge utilities all follow
-the same values. Prefer this over repeating equivalent utility classes across the app.
-[Theming](./docs/learn/theming.md#setting-a-theme) explains which selector each kind of
-token needs.
+The kit's own CSS arrives with its components. Do not `@import` `themelia-ui/style.css` or
+`themelia-ui/core.css` here as well: that inlines a second copy.
 
-### 2. Change one instance with `className`
+The bridge is a Tailwind theme declaration generated from Themelia's variables. It does two
+things:
 
-Public components pass `className` to their root element. Tailwind utilities live in the
-utilities layer, after Themelia's component layer, so they can override one instance without
-`!important`, selector escalation, `tailwind-merge`, or runtime class rewriting:
+1. Utilities read the live theme. `bg-primary`, `text-muted-foreground`, `rounded` (the
+   container radius), `rounded-sm` (the item radius), `p-padding`, `gap-gap-sm` and
+   `shadow-lg` resolve through Themelia's variables at the element, so they follow dark mode,
+   nested providers and density.
+2. It keeps Tailwind's defaults from replacing the variables both define, such as
+   `--radius-sm`, `--text-sm` and `--font-sans`. Import it even if you never write one of
+   its utilities.
 
-```tsx compile
-import { Button } from "themelia-ui/base/buttons"
-import "themelia-ui/base/buttons.css"
+Tailwind compiles utilities into the `utilities` layer, after Themelia's `components` layer,
+so a utility in `className` overrides a component's own rule. There is no need for
+`!important` or `tailwind-merge`.
 
-export function CheckoutButton() {
-  return (
-    <Button fullWidth className="rounded-pill shadow-xl sm:w-auto">
-      Continue to payment
-    </Button>
-  )
-}
+```tsx
+<Button className="rounded-pill px-padding shadow-lg">Approve</Button>
 ```
 
-Use local utilities for a real local exception. If the same override appears repeatedly,
-move the decision into a theme variable or an application-owned wrapper.
+## Overrides
 
-### 3. Customize a region with stable CSS hooks
+Use the narrowest override that expresses the decision:
 
-Every public component exposes a `{component-name}--component` root class. Named regions use
-`--header`, `--body`, `--footer`, and similar BEM hooks. `data-slot` attributes expose
-anatomy, and the state attributes Base UI sets (`data-open`, `data-checked`,
-`data-disabled`, `data-highlighted`, `data-popup-open`) expose state:
+1. **Across the product:** set a theme variable, as in [Theming](#theming).
+2. **One instance:** pass `className`.
+3. **A part of a component:** select its stable hooks. Each public component carries a
+   `{name}--component` class on its root and `{name}--{region}` classes on named regions;
+   parts carry `data-slot`; states carry the attributes Base UI sets, such as `data-open`,
+   `data-checked`, `data-disabled`, `data-highlighted` and `data-popup-open`.
 
 ```css
 .billing-actions .button--component {
@@ -240,127 +237,24 @@ anatomy, and the state attributes Base UI sets (`data-open`, `data-checked`,
 }
 ```
 
-Application CSS is unlayered and therefore wins over Themelia's named cascade layers. These
-public hooks are safer than hashed CSS Module names or package internals. Radix's
-`[data-state="open"]` matches nothing here.
-
-## Theming
-
-The theme is a contract, not a parallel stylesheet for every component. Most rebrands change
-the shadcn-shaped color, radius, shadow, chart, and sidebar seeds. Shared type, spacing,
-density, controls, focus, motion, media, and shell variables handle broader system choices.
-Component-owned variables remain implementation details unless a reference explicitly calls
-one an extension seam.
-
-The exhaustive public contract is documented in [`src/styles/TOKENS.md`](src/styles/TOKENS.md).
-[`FACTORS.md`](src/styles/FACTORS.md) explains the three global scale factors, and
-[`SCOPES.md`](src/styles/SCOPES.md) explains how derived variables stay live inside nested
-themes.
-
-### Theme from React
-
-Use `UIProvider` when theme choices and display defaults come from application state:
-
-```tsx fragment — App and Toolbar are supplied by the consuming application
-import { UIProvider } from "themelia-ui/ui-provider"
-
-<UIProvider
-  config={{
-    colorScheme: "dark",
-    density: "compact",
-    scale: 1,
-    theme: {
-      colors: {
-        primary: "oklch(0.7 0.14 165)",
-      },
-    },
-  }}
->
-  <App />
-  <UIProvider config={{ density: "comfortable" }}>
-    <Toolbar />
-  </UIProvider>
-</UIProvider>
-```
-
-A nested provider creates a nested theme/config scope. Values it does not name inherit from
-the parent. The more precise boundaries are:
-
-- `UIRoot` applies application-wide React defaults without rendering a layout element.
-- `UIScope` changes theme and configuration for one subtree.
-- `Scope` applies CSS variables only and creates the boundary derived tokens need.
-- `UIPortalHost` keeps menus, tooltips, selects, and other portals inside a nested scope.
-
-See [Provider and scoping](./docs/learn/provider-and-scoping.md) for portal behavior, multiple
-React roots, SSR, and strict CSP configuration.
-
-### Light and dark themes
-
-The default theme responds to all supported signals:
-
-```html
-<html class="dark">
-<html data-theme="dark">
-<!-- With colorScheme="system", prefers-color-scheme is honored automatically. -->
-```
-
-When authoring theme overrides, define both the light and dark values your brand changes.
-Setting `colorScheme` on `UIProvider`, `UIRoot`, or `UIScope` manages the corresponding scope
-for you.
-
-### CSS, generated palettes, and interactive themes
-
-- Write a small application override file for the common case.
-- Use `deriveThemePalette` from `themelia-ui/theming` to derive coherent CSS variables from
-  a brand seed.
-- Use `features/theme-tweaker` when users need to edit, preview, and serialize a complete
-  theme at runtime; persistence stays in consumer-owned state.
-- Use the published `tokens.json` DTCG artifact to share the token contract with design tools.
-
-The full guide covers all four paths in [Theming](./docs/learn/theming.md).
+Ordinary unlayered CSS wins over every Themelia layer, whatever the import order. Select the
+documented hooks, not hashed CSS Module class names, which change between releases.
 
 ## Composition
 
-Themelia is meant to produce application-specific components without absorbing application
-policy. Start with the highest-level family that already owns the interaction, then move down
-only when you need more control.
+Start from the highest tier that already owns the job, and move down only when you need more
+control: use a block, configure it through props, compose your own from features and base
+modules, and use exported parts and hooks when the behaviour is right but the presentation is
+not.
 
-| Layer | Owns | Typical consumer use |
-| --- | --- | --- |
-| `typography/` | Text roles | Consistent hierarchy, semantics, truncation, and color. |
-| `primitives/` | One formatted value | Money, dates, names, dimensions, contact values. |
-| `base/` | One generic UI concept | Buttons, fields, menus, cards, tables, feedback, structure. |
-| `layout/` | Page and application geometry | Route shells without owning routing or data. |
-| `features/` | An interaction lifecycle | Controlled state, callbacks, accessors, slots, parts, hooks. |
-| `patterns/` | A subject-shaped arrangement | Analytics, timelines, onboarding, and similar compositions. |
-| `admin/patterns/` | Terminal admin presentation | Admin-specific arrangements built only from general families. |
-
-The composition ladder is:
-
-1. Ordinary props.
-2. Controlled state and callbacks.
-3. Accessors that adapt application records.
-4. Named slots and render props.
-5. Exported parts.
-6. Headless hooks.
-7. Documented multi-family recipes.
-
-Not every family needs every rung. A passive badge needs props; a data view or editor needs
-several controlled seams.
-
-### Build a business-specific component
-
-This component understands invoices. The package does not. The application owns the record,
-permissions, mutation, route, analytics, and product copy; Themelia owns the page geometry,
-metadata structure, action semantics, focus behavior, and theme:
-
-```tsx fragment — Invoice and application policy belong to the consumer
+The application owns what is specific to it. Here it owns the invoice, the permission to
+collect payment and the mutation; Themelia owns the page geometry, the metadata layout, the
+action semantics, focus and the theme:
+
+```tsx
 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"
 
 function InvoiceDetail({ invoice, onCollectPayment }) {
   return (
@@ -387,165 +281,64 @@ function InvoiceDetail({ invoice, onCollectPayment }) {
 }
 ```
 
-Wrap a family when your product needs a stable local name or defaults. Compose several public
-families when they form a product concept. Use exported parts or a headless hook when the
-lifecycle is correct but the presentation is not. Contribute a new package abstraction only
-when the concept is domain-neutral, repeats across products, and keeps application policy at
-the boundary.
-
-Read the complete [composition guide](./docs/learn/composition.md) for dashboards, resource
-indexes, forms, settings areas, and the wrap/compose/contribute decision.
-
-## Why CSS instead of Tailwind internally?
-
-Tailwind is optimized for styling code an application owns. A distributed component library
-has a different job: it needs stable implementation styles, live runtime themes, scoped
-inheritance, and predictable overrides in applications that may use any build stack.
-
-| Library concern | Themelia's CSS-first answer |
-| --- | --- |
-| Work without consumer tooling | Precompiled family CSS; no Tailwind plugin, content scan, preset, or PostCSS setup is required. |
-| Change a whole product consistently | Shared custom properties let one decision reach every component. |
-| Theme a subtree at runtime | CSS inheritance and scope boundaries update descendants without rebuilding classes or remounting components. |
-| Avoid class conflicts | CSS Modules isolate implementation classes; public BEM and state hooks remain deliberate. |
-| Make consumer overrides predictable | Named cascade layers establish precedence instead of runtime class-string surgery. |
-| Keep variants typed | `cvm()` provides `cva`-shaped typed variants that resolve to CSS Module class maps. |
-| Load only what is used | Each exact component family publishes its own stylesheet and optional peer boundary. |
-
-This is not a rejection of Tailwind. It is a separation of responsibilities:
-
-- **Themelia CSS** owns reusable component presentation and the global design contract.
-- **Tailwind in your app** owns route layout, responsive composition, and genuine local
-  exceptions.
-- **The bridge** makes both systems read the same live tokens.
-
-The cascade replaces `tailwind-merge`: there is no runtime parsing or merging of class
-strings.
-
-## Imports and optional peers
-
-Every component family is published on an exact subpath. Shipping code should prefer those
-subpaths so optional features never leak into unrelated bundles:
-
-```ts compile
-import { Money } from "themelia-ui/primitives"
-import { Button } from "themelia-ui/base/buttons"
-import { DataTable } from "themelia-ui/features/table"
-import { Page } from "themelia-ui/layout/page"
-import { MetricGrid } from "themelia-ui/patterns/analytics"
-import { UIProvider } from "themelia-ui/ui-provider"
-
-void [Money, Button, DataTable, Page, MetricGrid, UIProvider]
-```
-
-The root `themelia-ui` export is optional-peer-free and convenient for prototypes. Exact
-subpaths are the production default. Heavier capabilities such as tables, charts, maps,
-drag-and-drop, rich text, and React Hook Form declare optional peers only on the families
-that use them.
+[Composition](docs/learn/composition.md) covers dashboards, resource indexes, forms and
+settings areas, and when to wrap, compose or contribute a component.
 
-## Choose and discover components
+## Find a component
 
-Search by the job you need, not by guessing a component name:
+Search the catalogue that ships with the package, offline, by what the interface must do:
 
 ```bash
-node node_modules/themelia-ui/scripts/consumer/find-component.mjs "key value facts"
+node node_modules/themelia-ui/scripts/consumer/find-component.mjs "mobile filters for a table" --explain
 ```
 
-The command searches public symbols, family identifiers, selection guidance, preview routes,
-and recipes. It prints exact JavaScript and CSS imports plus “choose when” and “avoid when”
-guidance. Use `--layer=base`, `--family=`, `--profile=`, `--peer=`, `--route=`, `--symbol=`,
-or `--json` for precise queries, and `--explain` for matched components, reasons and API
-anchors, as in `node node_modules/themelia-ui/scripts/consumer/find-component.mjs "mobile filters for a table" --explain`.
-See [Composition](docs/learn/composition.md) for ownership decisions and checked examples.
+Each match comes with its exact import and guidance on when to choose it and when to avoid
+it. `--json` prints complete records, and `--help` lists the filters.
 
-The package also ships an offline agent skill with the same generated component catalogue:
+The package also ships a skill for coding assistants, built from the same catalogue:
 
 ```bash
 node node_modules/themelia-ui/scripts/consumer/install-skill.mjs --project=.
 ```
 
-It installs into `.agents/skills/` and `.claude/skills/` without overwriting a skill the
-package did not create.
-
-## Architecture
-
-Layers compose downward, never in reverse. Layout and features are siblings; a pattern may
-compose both. The package never imports routing, fetching, persistence, translation, or
-application-domain state.
-
-Components that own visible or accessible copy expose typed default strings and partial
-overrides. Public components expose stable root and region hooks. Modal surfaces use the
-native `<dialog>` top layer; anchored surfaces use Base UI's collision-aware positioning.
-
-## Verification
-
-`npm run verify` runs the static checks in parallel beside the unit tests and one library
-build, then the checks that read `dist/`. `npm run verify -- --list` names every check;
-`npm run verify composition bem` runs just those. The browser suites run separately under
-`npm test`, over every preview route.
-
-```bash
-npm run verify          # architecture, tokens, CSS, docs, types, lint, unit tests, dist
-npm test                # Playwright interactions, accessibility, visuals, themes, geometry
-npm run verify:release  # on a clean tree: every check, consumer fixture and browser suite
-npm run dev             # local component and documentation preview
-```
-
-A release run refuses a dirty tree and prints the commit it passed. The checks cover CSS
-composition and scoping, tokens, the Tailwind bridge, package exports, optional-peer
-boundaries, accessibility, visuals, SSR, CSP, and disposable consumer applications.
-
-## Status
-
-<!-- GENERATED:status by scripts/gen-status-docs.mjs — do not edit. -->
-
-`2.0.1`. 97 component families across 8 layers — admin 2, base 53, features 24, foundation 4, layout 9, patterns 3, primitives 1, typography 1.
-
-The package publishes 99 exact JavaScript entrypoints and 93 exact CSS entrypoints. There are no broad aggregate barrels: a consumer imports the family it uses.
-
-Profiles are a dependency ceiling rather than a product taxonomy — admin 2, general 95. Every family is stable.
-
-Oxlint: 0 warnings.
-
-Whether a given tree may publish is not stated here. `npm run verify:release` decides, on
-a clean tree, and names the commit it passed.
-
-<!-- /GENERATED:status -->
+It installs into `.agents/skills/` and `.claude/skills/`, and never overwrites a skill it did
+not install.
 
 ## Documentation
 
-[Documentation home](docs/README.md) routes content by audience: Learn, Components, Build,
-and maintainer diagnostics.
+The [documentation index](docs/README.md) groups every document by audience.
+
+Guides:
 
 - [Installation and CSS loading](docs/learn/installation.md)
-- [Changelog](CHANGELOG.md)
-- [Upgrading to 2.0](docs/learn/migration.md#upgrading-to-20)
-- [Theming and Tailwind v4](docs/learn/theming.md)
+- [Theming and Tailwind CSS v4](docs/learn/theming.md)
 - [Provider and scoping](docs/learn/provider-and-scoping.md)
-- [Composition model](docs/learn/composition.md)
+- [Composition](docs/learn/composition.md)
 - [Framework wiring](docs/learn/framework-wiring.md)
 - [Forms](docs/learn/forms.md)
 - [Localization](docs/learn/i18n.md)
 - [Troubleshooting](docs/learn/troubleshooting.md)
-- [Public API index](docs/generated/public-api.md)
-- [Component catalogue](docs/generated/components/INDEX.md)
-- [Exact JavaScript, CSS, and peer imports](docs/generated/imports.md)
-- [Complete token contract](src/styles/TOKENS.md)
+- [Verifying a consuming application](docs/learn/verification.md)
 
-## Development
+Reference, generated from the source when the package is built. It ships in the package
+under `node_modules/themelia-ui/docs`, and the links open the latest published copy:
 
-```bash
-npm run dev
-npm run build:lib
-npm run find <term>
-npm run docs:sync-skill
-npm run verify
-```
+- [Component catalogue](https://unpkg.com/themelia-ui/docs/generated/components/INDEX.md)
+- [Public API index](https://unpkg.com/themelia-ui/docs/generated/public-api.md)
+- [Imports and optional peers](https://unpkg.com/themelia-ui/docs/generated/imports.md)
+- [Theme variables](src/styles/TOKENS.md)
+- [Recipes](https://unpkg.com/themelia-ui/docs/build/recipes.md)
+
+Upgrading and support:
+
+- [Changelog](CHANGELOG.md)
+- [Compatibility and migration](docs/learn/migration.md)
+- [API compatibility policy](docs/learn/api-compatibility.md)
+- [Security policy](SECURITY.md)
 
-Generated files identify their owner in a header. Regenerate barrels, exports, CSS types,
-themes, indexes, references, and status sections through their scripts rather than editing
-them by hand.
+To work on the library itself, see
+[CONTRIBUTING.md](https://github.com/nicolasvlachos/themelia-ui/blob/master/CONTRIBUTING.md).
 
 ## License
 
-MIT
+Themelia UI is released under the [MIT License](LICENSE).