themelia-ui 1.0.0

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

@@ -0,0 +1,266 @@
+---
+name: themelia-ui
+description: Use when a React consumer is selecting, importing, composing, theming, localizing, or integrating themelia-ui components, including forms, routing, data, SSR, CSP, and consumer CSS overrides. Do not use for maintaining package internals.
+---
+
+<!-- GENERATED by themelia-ui/scripts/gen-agent-skill.mjs -->
+<!-- GENERATED by themelia-ui/scripts/gen-agent-skill.mjs -->
+# Consuming Themelia UI
+
+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,
+`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
+   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
+   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.
+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.
+
+## Installed-package authorities
+
+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/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/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 |
+
+## Find the right family
+
+<!-- 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
+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 --peer=@tanstack/react-table
+node node_modules/themelia-ui/scripts/consumer/find-component.mjs --help
+```
+
+It indexes 98 component families, 368 attributed live recipes, and
+137 live preview routes by public symbol, family id, recipe title, preview route,
+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.
+<!-- /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
+  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.
+  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
+  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
+  where no kit role owns it.
+- 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
+
+<!-- GENERATED:layers by scripts/gen-agent-skill.mjs — do not edit between these markers. -->
+| layer | families | 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` | 25 | 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` |
+
+98 families, 785 public components, 1097 exported symbols in total.
+<!-- /GENERATED:layers -->
+
+Dependencies flow downward:
+
+```text
+foundation → typography → primitives → base ─┬─ layout ────┐
+                                             ├─ features ──┼→ patterns → 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.
+
+Use the layers 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.
+
+Application-specific cards, pages, workflows, and business components should normally be
+compositions of these families. 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.
+
+## 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.
+
+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.
+<!-- /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.** 91 of 98 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.
+
+`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.
+
+Import consumer overrides after the kit. Its 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
+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.
+
+| peer | reachable only from |
+| --- | --- |
+| `@dnd-kit/core` | `features/kanban` |
+| `@dnd-kit/sortable` | `features/kanban` |
+| `@dnd-kit/utilities` | `features/kanban` |
+| `@tanstack/react-table` | `features/data-view`, `features/products`, `features/table` |
+| `@tiptap/core` | `features/rich-text-editor/tiptap` |
+| `@tiptap/pm` | `features/rich-text-editor/tiptap` |
+| `@tiptap/starter-kit` | `features/rich-text-editor/tiptap` |
+| `leaflet` | `features/map` |
+| `leaflet-draw` | `features/map` |
+| `leaflet.fullscreen` | `features/map` |
+| `leaflet.markercluster` | `features/map` |
+| `react-hook-form` | `features/sync`, `forms-rhf` |
+| `react-leaflet` | `features/map` |
+| `react-leaflet-markercluster` | `features/map` |
+| `recharts` | `base/chart`, `patterns/analytics` |
+<!-- /GENERATED:peers -->
+
+## Provider, scopes, themes, and portals
+
+Use `UIRoot` once for app defaults without adding a layout element. Use `UIScope` when one
+subtree changes config, `Scope` when it changes raw tokens, and `UIPortalHost` when portalled
+content must inherit a regional theme or density. `UIProvider` remains the compatibility
+composition of root and scope.
+
+`colorScheme` is top-level configuration; `defaultCurrency` belongs inside `money`:
+
+```tsx compile
+import { UIProvider } from "themelia-ui/ui-provider"
+
+export function ScopedPreview() {
+  return (
+    <UIProvider
+      config={{ colorScheme: "dark", density: "compact", money: { defaultCurrency: "EUR" } }}
+    >
+      <main>Preview</main>
+    </UIProvider>
+  )
+}
+```
+
+Theme through the public contract in `node_modules/themelia-ui/src/styles/TOKENS.md`.
+The four global factors are `--scale`, `--space-scale`, `--density-scale`, and
+`--text-scale`; the three specific factors default to `--scale`. Use a documented scope
+boundary for subtree overrides so derived tokens recompute there. Component-level variables
+are implementation plumbing unless the public token reference explicitly promotes them.
+
+Import application overrides after kit CSS. Kit component rules are layered, so ordinary
+unlayered consumer CSS wins without `!important`. Target stable documented `data-slot`,
+`data-state`, or BEM hooks; never target CSS Module hashes. If the application uses Tailwind
+v4, follow `references/theming.md` and import the supplied bridge so colliding token names
+continue to resolve to the kit contract.
+
+Read `references/provider-and-scoping.md` before using nested providers, document targets,
+portals, strict CSP, or streaming SSR. Read `references/theming.md` before defining a theme.
+
+## Forms, copy, accessibility, and framework wiring
+
+- `themelia-ui/forms` is the dependency-free field binding contract.
+  `themelia-ui/forms-rhf` is the optional react-hook-form adapter. Other form libraries
+  implement the same interface; see `references/forms.md`.
+- Replace component-owned visible and accessible copy through the documented partial
+  `strings` object. Do not invent one-off string props. The application still owns message
+  lookup, locale selection, and domain copy; see `references/i18n.md`.
+- Preserve labels, descriptions, accessible names, focus return, dismissal, and keyboard
+  behavior when composing. Prefer role/name assertions over CSS selectors.
+- Wire links, loaders, mutations, permissions, analytics, persistence, server rendering,
+  and client boundaries at the consumer edge; see `references/framework-wiring.md`.
+
+## References: open only what the task needs
+
+| 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. 98 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. |
+<!-- /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/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 |
+| `references/api-compatibility.md` | checking the stable-major and deprecation contract |
+| `references/migration.md` | upgrading or replacing old/broad imports |
+| `references/troubleshooting.md` | diagnosing CSS, peers, portals, state, CSP, or resolution failures |
+| `references/verification.md` | testing an integration in a consuming application |
+
+## Consumer completion checklist
+
+- Exact family import and its CSS resolve from the installed package.
+- Only the selected families' 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.
+- Light/dark, compact/comfortable, custom theme, translated copy, narrow, and wide layouts pass.
+- SSR/RSC, CSP, portals, routing, and production bundling are exercised when the app uses them.
+- The result still reads as application composition: reusable mechanics from the package,
+  business policy from the consumer.

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

@@ -0,0 +1,35 @@
+# API compatibility
+
+Version 1.x treats exact package subpaths, exported names, callable signatures, and exported
+props/type members as compatibility surfaces. Public global theme tokens, documented
+`data-slot` and BEM hooks, and the `strings` contracts are also consumer contracts.
+
+## Change policy
+
+| change | compatibility |
+| --- | --- |
+| new subpath, export, or optional prop | additive |
+| optional prop becomes required | breaking |
+| export, prop, or subpath is removed | breaking |
+| prop type is narrowed | breaking |
+| 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.
+
+The repository snapshots every exported declaration and rejects removals, required-member
+changes, and incompatible type changes without a migration record. Package-resolution checks
+also validate ESM, CommonJS, declarations, CSS exports, and exact subpaths against the packed
+tarball.
+
+## What consumers should depend on
+
+Prefer the ready-made component, documented parts and hooks, global theme contract,
+`data-slot`, `data-state`, and BEM hooks. 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.