themelia-ui 1.0.3 → 2.0.1

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Use when a React consumer is selecting, importing, composing, theming, localizing, integrating or upgrading themelia-ui components — forms, routing, data, SSR, CSP, consumer CSS overrides, Tailwind, and migrating between versions with the packaged codemod. Do not use for maintaining package internals.
 ---
 
 <!-- GENERATED by themelia-ui/scripts/gen-agent-skill.mjs -->
@@ -24,6 +24,17 @@ uses CSS Modules over Base UI, publishes exact family subpaths, and has no `ui/`
 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.
 
+**Upgrading between versions** comes before any of that. Read the version's section in
+`references/migration.md`, then run the packaged codemod — dry first — and handle what it
+reports (removed tokens, overrides that now set a shared name, look-alike Tailwind utilities)
+by hand. Re-run the skill installer afterwards so this skill matches the installed version:
+
+```bash
+node node_modules/themelia-ui/scripts/consumer/codemod.mjs --dry-run src/
+node node_modules/themelia-ui/scripts/consumer/codemod.mjs src/
+node node_modules/themelia-ui/scripts/consumer/install-skill.mjs --project=.
+```
+
 ## Installed-package authorities
 
 These paths exist after installation and are the source of truth:
@@ -38,6 +49,8 @@ These paths exist after installation and are the source of truth:
 | `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/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
 
@@ -54,8 +67,8 @@ node node_modules/themelia-ui/scripts/consumer/find-component.mjs --peer=@tansta
 node node_modules/themelia-ui/scripts/consumer/find-component.mjs --help
 ```
 
-It indexes 98 component families, 376 attributed live recipes, and
-139 live preview routes by public symbol, family id, recipe title, preview route,
+It indexes 97 component families, 383 attributed live recipes, and
+118 live preview routes by public symbol, family 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.
@@ -88,12 +101,12 @@ Selection rules:
 | `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` |
+| `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` |
 
-98 families, 788 public components, 1102 exported symbols in total.
+97 families, 752 public components, 1070 exported symbols in total.
 <!-- /GENERATED:layers -->
 
 Dependencies flow downward:
@@ -144,7 +157,7 @@ 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
+**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.
@@ -183,10 +196,16 @@ There are 15 optional peer packages. A consumer only needs the peers reachable f
 
 ## 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.
+Use `UIRoot` once for app defaults without adding a layout element. It renders nothing and
+writes nothing to the page unless asked: pass `documentTarget="documentElement"` so the colour
+scheme and density reach the whole document, or wrap the app in `UIProvider`, which renders a
+scope 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.
+
+Dropdown, context, action and menubar menus render dark on a light page by design. That is
+the provider's `overlay.darkMenus` (default `true`); set it to `false` to let menus follow the
+page. Do not restyle a menu's colours in CSS to get the same effect.
 
 `colorScheme` is top-level configuration; `defaultCurrency` belongs inside `money`:
 
@@ -205,14 +224,17 @@ export function ScopedPreview() {
 ```
 
 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
+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.
 
 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
+unlayered consumer CSS wins 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
 v4, follow `references/theming.md` and import the supplied bridge so colliding token names
 continue to resolve to the kit contract.
 
@@ -237,7 +259,7 @@ 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. 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. |
+| `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. |
 <!-- /GENERATED:index-row -->
 | `references/components/INDEX.md` | opening one complete generated family API reference |
 | `references/imports.md` | confirming exact imports and optional-peer ownership |
@@ -250,7 +272,7 @@ portals, strict CSP, or streaming SSR. Read `references/theming.md` before defin
 | `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/migration.md` | upgrading between versions — what changed, the codemod, and what it leaves to you |
 | `references/troubleshooting.md` | diagnosing CSS, peers, portals, state, CSP, or resolution failures |
 | `references/verification.md` | testing an integration in a consuming application |
 

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

@@ -1,7 +1,7 @@
 # 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
+Within a major version, exact package subpaths, exported names, callable signatures, and
+exported props/type members are compatibility surfaces. Public global theme tokens, documented
 `data-slot` and BEM hooks, and the `strings` contracts are also consumer contracts.
 
 ## Change policy
@@ -19,16 +19,18 @@ 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.
 
-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.
+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.
 
 ## 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.
+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
+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