themelia-ui 2.0.0 → 3.0.0

package/docs/learn/provider-and-scoping.md

@@ -47,7 +47,7 @@ When an application embeds another:
 </UIScope>
 ```
 
-Its `config` is its **own overrides only**; inherited values already cascade in.
+Its `config` holds its **own overrides only**; the rest comes from the enclosing provider.
 
 `transparent` (default `true`) removes the element from layout with `display: contents`.
 Custom properties still inherit through it, because inheritance does not depend on the box.
@@ -60,7 +60,7 @@ below a slice as well as at it:
 ```tsx fragment — shape only, not a program
 <UIProvider config={{ theme: { colors: { primary: "blue", secondary: "green" } } }}>
   <UIScope config={{ theme: { colors: { primary: "red" } } }}>
-    {/* primary is red, secondary is still green */}
+    {/* useUIConfig().theme.colors: primary "red", secondary "green" */}
   </UIScope>
 </UIProvider>
 ```
@@ -69,6 +69,14 @@ This applies to every record-shaped field: `theme.colors`, `theme.palette`, `the
 `typography.fonts`, `typography.sizes` and `motion.durations`. Below them a record is a flat
 map of token to value, and a value is replaced, not merged.
 
+That is the configuration components read, and the CSS follows it: each scope writes the
+merged overrides on its element, so inside the nested scope above `--primary` is red and
+`--secondary` is green. Raw inputs (palette steps, radii, fonts, durations and the scale
+factors) inherit through every boundary. Semantic colours and type sizes do not: a `Scope`,
+or any other element on the boundary list, declares them again from the palette. To keep a
+colour across one of those, set it through `theme.palette` or declare it at the boundary
+list; see [Theming](./theming.md#setting-a-theme).
+
 ## Scope — tokens only
 
 Overriding a factor requires a **scope boundary**, not just any element:
@@ -79,6 +87,9 @@ Overriding a factor requires a **scope boundary**, not just any element:
 </Scope>
 ```
 
+`Scope` renders a `div` without layout. `render` picks another element, as on every
+component (`render={<section />}`), and `transparent={false}` gives it a box.
+
 Derived tokens are declared at `:root, [data-ui-scope], [data-density], [data-theme], .light,
 .dark` (see [`src/styles/SCOPES.md`](../../src/styles/SCOPES.md)). A plain
 `<div style={{ "--density-scale": 0.8 }}>` sets the variable and nothing reads it: the
@@ -113,7 +124,8 @@ Wrap the region in `UIPortalHost` and the popups render inside it instead:
 
 The host renders one `display: contents` element inside the scope, and every portal in the
 subtree targets it, so the popup inherits from the scope. DropdownMenu, ContextMenu, Select,
-Tooltip, HoverCard, Popover, NavigationMenu and Toaster all resolve it.
+Combobox, Tooltip, HoverCard, Popover, NavigationMenu and Toaster all resolve it. An
+`Overlay` needs no host: it renders in place, and the popups inside it portal into it.
 
 Precedence, most specific first:
 
@@ -163,7 +175,7 @@ ship the scrollbar rule in the consuming application's stylesheet:
 ```
 
 `disableStyleElements` does not disable kit behavior; it moves those small rules into the
-consuming app. It does not replace the normal `core.css`, family CSS, or `style.css` import.
+consuming app. It does not replace the normal `core.css`, module stylesheet, or `style.css` import.
 
 ## Reading the config
 
@@ -180,7 +192,7 @@ provider, so read `useDefaults` rather than hard-coding a size or variant.
 `useMoneyConfig`, `useDatesConfig`, `useOverlayConfig`, `useDensity`, `useScale`,
 `useFormatting`, `useTypographyConfig`. `useDefaults` takes the component's *own* defaults
 and merges the scope's over them, which keeps the values beside the component, makes the
-call order-independent, and lets an unused family tree-shake away.
+call order-independent, and lets an unused module tree-shake away.
 
 The provider holds stable display policy: money, dates, size, density, scale. Per-feature
 policy, query timing, domain accessors, data and callbacks stay props.
@@ -195,8 +207,8 @@ still take precedence over provider defaults.
 and supplies that state to its provider. Its internal editor state alone does not change
 an enclosing provider. Keep unfinished text edits separate from applied configuration:
 for example, validate a locale with `Intl.getCanonicalLocales` before passing it to
-formatting components. The [Theme Tweaker recipe](../generated/components/features--theme-tweaker.md)
-shows this wiring and keeps the last valid preview while a locale is being typed.
+formatting components. [Editing a theme at runtime](./theming.md#editing-a-theme-at-runtime)
+shows the wiring.
 
 ## Optional iPhone input zoom prevention
 

package/docs/learn/theming.md

@@ -1,38 +1,22 @@
 # Theming
 
-A theme author sets the **global contract** and stops. Most rebrands begin with the palette,
-semantic-colour, radius and shadow seeds in the default theme; the contract also includes
-the public type, spacing, motion, focus and layering controls.
-[`src/styles/TOKENS.md`](../../src/styles/TOKENS.md) lists every name and the current counts.
+A theme sets the **global contract** and stops there. Most rebrands begin with the palette,
+semantic colours, radii and shadows of the default theme; the contract also covers type,
+spacing, motion, focus and layering. [`src/styles/TOKENS.md`](../../src/styles/TOKENS.md)
+names the token for each role.
 
-The component-token layer is plumbing, not the theming surface: most of it is a `var()` off
-the contract, and the rest is geometry no theme would touch (`--separator-thickness: 1px`).
-Override component tokens only where a family reference names one as an extension point.
-
-## Editing a running app
-
-`ThemeTweaker` (`themelia-ui/features/theme-tweaker`) lets people change appearance, accent
-colour, density, corners and font while the app runs, and exports CSS theme values and
-provider configuration separately. Mount it as a floating button, a full-page route, or both.
-
-The application owns the theme and provider state, above its router:
-
-- Keep `useAppliedTheme` mounted there with `target="document"` and `manageModeClass={false}`.
-- Give the root `UIProvider` the shared config and `themeToStyle(theme)`.
-- Render the controlled editor with `apply={false}`.
-
-This keeps document portals and the provider scope in sync, and theme application does not
-depend on whether the panel is open. Persist valid config separately from unfinished field
-input, so typing a partial locale cannot break the app.
+Component tokens are not the theming surface: most are a `var()` off the contract, and the
+rest is geometry no theme would touch. Override one only where a module reference names it
+as an extension point.
 
 ## Setting a theme
 
-Declare the contract's names wherever you want them to apply. Which selector reaches a
-component depends on the kind of name.
+Where an override has to be declared depends on the kind of token.
 
-A **raw input** — `--radius`, a font stack, a palette primitive — is declared once at
-`:root` and inherits everywhere. `--primary` resolves through `--brand-600` in light and
-`--brand-350` in dark, so a rebrand sets the primitives and every semantic follows:
+A **raw input** (`--radius`, `--radius-sm`, a font stack, a palette step, a scale factor) is
+declared once at `:root` and inherits everywhere. The semantic colours resolve through the
+palette (`--primary` is `--brand-600` in light and `--brand-350` in dark), so a rebrand that
+sets palette steps reaches every scope:
 
 ```css
 :root {
@@ -43,16 +27,11 @@ A **raw input** — `--radius`, a font stack, a palette primitive — is declare
 }
 ```
 
-A **semantic** — `--primary`, `--background`, `--border` — re-derives at every scope
-boundary, and the provider's own element is one. Set on `:root` alone, it is re-declared at
-that element and no component sees it. Pass it through the provider, which writes it on the
-boundary itself:
-
-```tsx fragment — shape only, not a program
-<UIProvider config={{ theme: { colors: { primary: "oklch(0.55 0.19 250)" } } }}>
-```
-
-or declare it at the boundaries, in the list the package itself uses:
+A **semantic** token (`--primary`, `--background`, `--border`) is declared again at every
+scope boundary: `:root`, `[data-ui-scope]`, `[data-density]`, `[data-theme]`, `.light` and
+`.dark`. Every provider renders a boundary, so a semantic set on `:root` alone stops at the
+first one. Declare it at the same list, which reaches every scope and the popups portalled to
+`<body>`:
 
 ```css
 :root, [data-ui-scope], [data-density], [data-theme], .light, .dark {
@@ -60,16 +39,29 @@ or declare it at the boundaries, in the list the package itself uses:
 }
 ```
 
-For a subtree, use a scope boundary rather than a bare element — see
+That rule applies in light and dark alike. For a separate dark value, follow it with a rule
+on the dark selectors shown in [`SCOPES.md`](../../src/styles/SCOPES.md).
+
+A provider takes the same values as config and writes them on its own element:
+
+```tsx fragment — shape only, not a program
+<UIProvider config={{ theme: { colors: { primary: "oklch(0.55 0.19 250)" } } }}>
+```
+
+Colours passed this way reach the provider's subtree down to the next boundary: a nested
+provider, `Scope` or `data-density` region declares the kit's colours again, and popups
+portalled outside the provider never see them. `theme.palette` reaches every boundary inside
+the provider, because each one derives its colours from the palette.
+
+For a subtree, use a scope boundary rather than a bare element; see
 [Provider and scoping](./provider-and-scoping.md#scope--tokens-only). Derived tokens resolve
 **where they are declared**, so a variable set on an element that is not a boundary is set
 and never read.
 
 ## Start with the shared controls
 
-Most layout adjustments need only the surface insets, row insets, spacing factor, font
-family, and the two radii. These controls follow the component's role rather than its
-feature name:
+Most layout adjustments need only the surface insets, row insets, density factor, font
+family and the two radii. They follow a component's role rather than its name:
 
 ```css
 :root {
@@ -83,11 +75,6 @@ feature name:
 }
 ```
 
-**Fonts.** The kit ships Geist for text and Geist Mono for code and identifiers (SIL OFL 1.1),
-as variable-weight woff2 files beside `core.css`, one per script. A browser downloads a file
-only when text in that script renders in that family, so a theme that sets `--font-sans` and
-`--font-mono` to its own fonts downloads none of them.
-
 - Cards, framed ContentBlocks and overlay bodies share the surface X/Y insets.
 - Overlay headers and footers use the same horizontal inset and 75% of the vertical inset;
   the header adds a small optical inset above its title.
@@ -95,16 +82,20 @@ only when text in that script renders in that family, so a theme that sets `--fo
   radii, so rows sit concentric.
 - Dark mode inherits the chosen fonts.
 
-Compose title/description regions with CardHeader, ContentBlock or OverlayHeader; action
-regions with CardFooter or OverlayFooter; and label/value facts with MetadataList. These
-components own their spacing, so the application does not reproduce it.
+**Fonts.** The kit ships Geist for text and Geist Mono for code and identifiers (SIL OFL 1.1),
+as variable-weight woff2 files beside `core.css`, one per script. A browser downloads a file
+only when text in that script renders in that family, so a theme that sets `--font-sans` and
+`--font-mono` to its own fonts downloads none of them.
 
-`--content-block-p` and `--overlay-region-p` remain supported for local exceptions. Leave
-them unset when the surface should follow the theme.
+Compose title and description regions with CardHeader, ContentBlock or OverlayHeader, action
+regions with CardFooter or OverlayFooter, and label/value facts with MetadataList. These
+components own their spacing, so the application does not reproduce it.
+`--content-block-p` and `--overlay-region-p` override one surface's inset locally; leave them
+unset so the surface follows the theme.
 
 ## Scale
 
-Three factors, and no per-family ones:
+Three factors, and no per-module ones:
 
 | Factor | Multiplies |
 |---|---|
@@ -114,50 +105,83 @@ Three factors, and no per-family ones:
 
 Setting `--scale` alone moves the whole system. `UIProvider`'s `typography.scale` sets
 `--text-scale` for a scope without changing its geometry.
-[`src/styles/FACTORS.md`](../../src/styles/FACTORS.md) is the authority.
+[`src/styles/FACTORS.md`](../../src/styles/FACTORS.md) is the reference.
 
 Named `density` presets set only `--density-scale`, so compact and comfortable regions
 change spacing, control heights and row rhythm without resizing readable type. Controls are
-34, 30 and 24px at the default and 32, 28 and 23px under `compact`. Use explicit `scale`
-when the entire scoped UI should move together.
+34, 30 and 24px at the default and 32, 28 and 23px under `compact`. Use `scale` when the
+whole scoped UI should move together.
 
 All three are raw inputs: set them on `:root`, with a `density` preset, or on a boundary such
 as [`Scope`](./provider-and-scoping.md#scope--tokens-only). On a plain nested element nothing
 re-derives from them.
 
-A single family cannot be scaled on its own; scale a region with a scope instead. A
-family-shaped token name is not a tuning seam. Use the three public factors rather than
-reconstructing component calculations.
+A single module cannot be scaled on its own; scale a region with a scope instead, and use the
+three factors rather than reconstructing component calculations.
 
 ## Dark mode
 
-Three signals, all answered:
-
-```css
-.dark { … }
-[data-theme="dark"] { … }
-@media (prefers-color-scheme: dark) { … }
-```
+The kit answers three signals: a `.dark` class, `data-theme="dark"`, and
+`prefers-color-scheme: dark` when no explicit scheme is set. A dark-only override should
+answer all three, because an app that toggles a class and an app that sets an attribute are
+both normal. Use the selectors in [`SCOPES.md`](../../src/styles/SCOPES.md), which also reach
+the bare boundaries nested under a dark ancestor.
 
-A dark-only override should answer all three: an app that toggles a class and an app that
-sets an attribute are both normal, and honouring only one leaves the other half-themed.
-
-A bare token boundary nested under an explicit dark ancestor — a `Scope`, a `data-density`
-region, a nested provider on the default `system` scheme — re-derives the dark values. An
-explicit light island inside a dark tree keeps its own boundary light, but a bare boundary
-inside that island re-derives dark again; give it its own `data-theme`, or use `UIScope`,
-which writes the resolved scheme on each boundary it renders.
-[`src/styles/SCOPES.md`](../../src/styles/SCOPES.md) shows the selectors.
+A bare boundary under an explicit dark ancestor (a `Scope`, a `data-density` region, or a
+nested provider on the default `system` scheme) resolves the dark values. An explicit light
+island inside a dark tree keeps its own boundary light, but a bare boundary inside that
+island resolves dark again; give it its own `data-theme`, or use `UIScope`, which writes the
+resolved scheme on each boundary it renders.
 
 In CSS Modules, `.dark` is hashed like any other class. Write a dark rule as
 `:global(.dark)`, or it matches nothing and the theme silently does not apply.
 
-## Runtime theming
+## Editing a theme at runtime
+
+`ThemeTweaker` (`themelia-ui/features/theme-tweaker`) lets people change appearance, accent
+colour, density, corners and font while the app runs, and exports CSS theme values and
+provider configuration separately. Mount it as a floating button, a full-page route, or both.
 
-`features/theme-tweaker` edits CSS theme values and provider defaults at runtime. Connect
-`onConfigChange` to application state and pass valid configuration to the provider; mounted
-descendants update without a remount. Use its export callbacks to persist the result in
-your application. See [runtime provider configuration](./provider-and-scoping.md#updating-defaults-at-runtime).
+The application owns the theme and provider state, above its router:
+
+- `useAppliedTheme`, mounted there with `target: "document"` and `manageModeClass: false`,
+  applies the theme whether or not the editor is open.
+- The root `UIProvider` takes the same config and `themeToStyle(theme)`.
+- The editor is controlled, with `apply={false}`.
+
+```tsx compile
+import { useRef, useState, type ReactNode } from "react"
+import { UIProvider, type UIConfig } from "themelia-ui/ui-provider"
+import {
+  ThemeTweaker, createTheme, themeToStyle, useAppliedTheme, type ThemeDefinition,
+} from "themelia-ui/features/theme-tweaker"
+import "themelia-ui/features/theme-tweaker.css"
+
+export function ThemedApp({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState<ThemeDefinition>(() => createTheme())
+  const [config, setConfig] = useState<UIConfig>({ colorScheme: "system" })
+  const selfRef = useRef<HTMLDivElement>(null)
+  useAppliedTheme({ theme, target: "document", selfRef, apply: true, manageModeClass: false })
+
+  return (
+    <UIProvider config={config} style={themeToStyle(theme)}>
+      {children}
+      <ThemeTweaker
+        value={theme}
+        onValueChange={setTheme}
+        config={config}
+        onConfigChange={setConfig}
+        apply={false}
+      />
+    </UIProvider>
+  )
+}
+```
+
+Mounted descendants update without a remount. Persist valid configuration apart from
+unfinished field input, so a half-typed locale cannot break the app, and use the export
+callbacks to save the result. See
+[runtime provider configuration](./provider-and-scoping.md#updating-defaults-at-runtime).
 
 ## Synthesising a theme in code
 
@@ -171,8 +195,10 @@ const overrides = deriveThemePalette({ primary: "#3b82f6" })
 // { "--primary": "#3b82f6", "--primary-foreground": "oklch(0.18 0.01 260)", … }
 ```
 
-The derived values stay CSS — `color-mix(in oklch, var(--primary) 10%, var(--background))`
-rather than a computed literal — so they keep following the tokens they derive from.
+The keys are semantic custom properties, so write them at the boundary list or pass them to
+a `Scope`'s `vars`. The derived values stay CSS
+(`color-mix(in oklch, var(--primary) 10%, var(--background))` rather than a computed
+literal), so they keep following the tokens they derive from.
 
 `readableForeground(background)` **measures** WCAG contrast against both candidates and
 returns the better one, with the ratio and whether it clears AA:
@@ -193,25 +219,23 @@ Both functions are also re-exported from `features/theme-tweaker`.
 tools like Style Dictionary. Colours are OKLCH objects with a `hex` fallback:
 
 ```json
-{ "$value": { "colorSpace": "oklch", "components": [0.45, 0.124, 167.35], "hex": "#00785f" } }
+{ "$value": { "colorSpace": "oklch", "components": [0.45, 0.124, 167.35], "hex": "#006a47" } }
 ```
 
-Two kinds of value are deliberately absent, each named in its own `$extensions`:
+Two kinds of value are left out, and the file lists each one under its `$extensions`:
 
 - **Mixed colours.** `--destructive-accent` and the inverse steps are `color-mix()` over
   other tokens; DTCG has no type for a mix, and resolving one would bake one theme's value in.
-- **Shadows.** Each is a multi-layer shadow whose colour is a `color-mix`; resolving it
+- **Shadows.** Each is a multi-layer shadow whose colour is a `color-mix()`; resolving it
   would bake one theme's ink in.
 
-Every `$type`, value and `{reference}` in the file is validated, and no dark token aliases
-a skipped light token.
-
 [dtcg]: https://www.designtokens.org/TR/drafts/format/
 
 ## Tailwind CSS v4
 
 The kit ships no Tailwind and needs none. If your application already uses Tailwind v4,
-import the bridge and its utilities resolve against this contract:
+import the bridge after Tailwind and the kit's stylesheet, and its utilities resolve against
+this contract:
 
 ```css
 @import "tailwindcss";
@@ -220,30 +244,32 @@ import the bridge and its utilities resolve against this contract:
 ```
 
 `bg-primary` is `var(--primary)`, `rounded-sm` is the kit's inner radius, `p-md` is
-`var(--space-md)`, `text-sm` is `calc(0.875rem * var(--text-scale, var(--scale)))`. The
-container radius has no named utility — `rounded` stays Tailwind's own — so write
+`var(--space-md)`, and `text-sm` is `calc(0.875rem * var(--text-scale, var(--scale)))`. The
+container radius has no named utility (`rounded` stays Tailwind's own), so write
 `rounded-(--radius)`. Every utility reads the token **at the element**, so a `.dark`
 subtree, a `[data-density="compact"]` scope, a nested `UIProvider` and a provider's
 `theme.radiusSm` or `typography.fonts` all move Tailwind's output the way they move the
 kit's own.
 
-**Import it even if you never write a kit-token utility.** Both projects descend from
-shadcn, so custom-property names collide — `--radius-sm` and `--radius-pill`, `--text-xs`
-through `--text-2xl`, `--shadow-*`, `--font-sans/serif/mono`, `--leading-*`, `--ease-*`.
-Tailwind emits its defaults onto `:root` inside `@layer theme`; when the kit is imported
-first, that layer sits **above** the kit's `tokens` layer. Without the bridge, Tailwind
-wins every shared name, among them:
+**Import the bridge even if you never write a kit-token utility.** Both projects descend
+from shadcn, so custom-property names collide: `--radius-sm`, `--text-xs` through
+`--text-2xl`, `--shadow-*`, `--font-sans/serif/mono`, `--leading-*`, `--tracking-*`,
+`--ease-*` and `--animate-*`. Tailwind emits its defaults onto `:root` inside `@layer theme`,
+and when the kit's layers are declared first, that layer sits **above** the kit's `tokens`
+layer. Every module stylesheet imports `core.css` too, so which comes first depends on the
+order your application imports its CSS. Without the bridge, Tailwind can win every shared
+name, among them:
 
 | what | kit | Tailwind takes it to |
 | --- | --- | --- |
-| `--radius-sm` | `0.5rem` — the kit's inner radius | `0.25rem` |
-| `--text-sm` | `calc(0.875rem * var(--text-scale, var(--scale)))` | `0.875rem` — **scoped type scaling stops working** |
+| `--radius-sm` | `0.5rem`, the kit's inner radius | `0.25rem` |
+| `--text-sm` | `calc(0.875rem * var(--text-scale, var(--scale)))` | `0.875rem`, and **scoped type scaling stops working** |
 | `--font-sans` | Geist first | Tailwind's system stack |
-| `--animate-pulse` | `cubic-bezier(0.4, 0, 0.2, 1)` | `cubic-bezier(0.4, 0, 0.6, 1)` |
+| `--animate-pulse` | `pulse 2s var(--ease-in-out) infinite` | `pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite` |
 
 The symptom is a slightly wrong radius and a density control that stops working, not an
 error. The bridge restates those names with the kit's own definitions, so Tailwind's
-override becomes a no-op. It is generated from the same public tokens.
+override becomes a no-op in either order. It is generated from the same public tokens.
 
 The bridge is two theme declarations and nothing else: no rules and no utilities, and
 Tailwind drops every key no utility uses, so it costs nothing you do not use. Keys that read

package/docs/learn/troubleshooting.md

@@ -2,38 +2,64 @@
 
 ## A component is unstyled
 
-Import its exact family stylesheet beside the JavaScript subpath, or import the complete
-`themelia-ui/style.css` once. A family stylesheet already imports `core.css`; importing
-core alone supplies tokens but no component rules.
+The JavaScript imports no CSS. Import the module's stylesheet beside the JavaScript subpath,
+or `themelia-ui/style.css` once. `core.css` alone supplies tokens but no component rules. See
+[Loading the CSS](./installation.md#loading-the-css).
 
-Keep application overrides after package CSS. The package uses cascade layers, so ordinary
-unlayered application CSS wins without `!important` or selector escalation.
+Overrides need no `!important` or selector escalation: the kit's rules are layered, and
+unlayered application CSS beats them.
+
+## Node throws on a `.css` import
+
+`ERR_UNKNOWN_FILE_EXTENSION` for a `.css` file means Node is running one of your own modules
+that imports a stylesheet, without a bundler. The kit's JavaScript imports none. Import the
+stylesheets where your bundler or framework processes CSS, or map `\.css$` to a stub in a
+test runner that runs your modules directly.
+
+## Jest: `Cannot use import statement outside a module`
+
+The package is ES modules, and Jest transforms nothing in `node_modules` by default. Exempt
+the package in `transformIgnorePatterns`. See [In Node](./installation.md#in-node).
 
 ## A subpath does not resolve
 
-There are no layer barrels such as `themelia-ui/base`. Use the generated
+There are no tier barrels such as `themelia-ui/base`. Use the generated
 [import table](../generated/imports.md) or run:
 
 ```bash
 node node_modules/themelia-ui/scripts/consumer/find-component.mjs "what the UI must do"
 ```
 
-Import the returned exact family path and its returned CSS path.
+Import the returned exact module path and its returned CSS path.
 
 ## An optional peer is missing
 
-Install only the peers listed for the imported family. The generated import table maps every
-optional peer to the exact families that reach it. If the error names a peer for a family not
+Install only the peers listed for the imported module. The generated import table maps every
+optional peer to the exact modules that reach it. If the error names a peer for a module not
 listed there, report it as a package containment defect.
 
-## A scoped theme or density does not apply
-
-Set tokens through `UIProvider` or `UIScope` config, on a `Scope` or other
-`[data-ui-scope]` element, on a theme signal, or on another documented scope boundary.
-Derived custom properties resolve where they are declared, so a source value set on an
-arbitrary descendant leaves the already-resolved derived value unchanged. A semantic colour
-or `--density-scale` set on `:root` alone is re-declared at the first boundary. See
-[Theming](./theming.md) and [Provider and scoping](./provider-and-scoping.md).
+## A theme or density override does not apply
+
+Derived tokens are declared at every scope boundary (`:root`, `[data-ui-scope]`,
+`[data-density]`, `[data-theme]`, `.light` and `.dark`) and resolve there. Which selector an
+override needs depends on the token:
+
+- **Raw inputs**, such as the radii, font stacks, palette steps, `--scale`,
+  `--density-scale` and `--text-scale`, are declared at `:root` only, so a value set on
+  `:root` reaches every scope. Inside a `data-density` preset region, the preset's
+  `--density-scale` applies instead.
+- **Semantic colours** such as `--primary` and `--background` are re-declared at every
+  boundary. Set on `:root` alone, they stop at the first boundary, and every provider renders
+  one. Declare them at the boundary list, or pass them through provider config.
+- **A provider's `theme.colors`** is written on the provider's own element, so a nested
+  provider, `Scope` or `data-density` region inside it declares the kit's colours again. For
+  colours that must reach every region, use the boundary list, or set palette steps
+  (`theme.palette`), which each nested boundary derives its colours from.
+- **A plain element** that is not a boundary sets the variable, and nothing re-derives from
+  it: the derived values were resolved above it. Wrap the region in `Scope`.
+
+See [Theming](./theming.md#setting-a-theme) and
+[Provider and scoping](./provider-and-scoping.md).
 
 ## A portal has the wrong theme
 
@@ -48,7 +74,7 @@ overrides that `<body>` popups must see belong in CSS at the scope boundaries. S
 
 A controlled value changes only when the consumer feeds the new value back. Connect the
 documented change callback to state, cache, or URL ownership. If the application does not
-need ownership, omit the controlled prop and use the family's documented default-value API
+need ownership, omit the controlled prop and use the module's documented default-value API
 when one exists.
 
 ## A link behaves like a button
@@ -61,20 +87,20 @@ element's semantics while applying the component's behaviour and geometry.
 
 Use `CSPProvider` with the request nonce. For a policy that forbids style elements entirely,
 set `disableStyleElements` and serve the documented Base UI behaviour rules from an external
-stylesheet. Family CSS itself is ordinary static CSS.
+stylesheet. The module stylesheets themselves are ordinary static CSS. See
+[Provider and scoping](./provider-and-scoping.md#strict-content-security-policy).
 
 ## The design looks inconsistent after overrides
 
-Override global semantic tokens first: colour roles, radius, spacing/density, typography,
-and control geometry. Component-level variables are implementation plumbing unless the
-family reference describes one as an extension point. Do not target hashed CSS Module
-names; use stable `data-slot` or BEM hooks, and for a state the attributes the primitives
-set (`data-open`, `data-checked`, `data-disabled`, `data-highlighted`, `data-popup-open`).
-Radix's `[data-state="open"]` matches nothing here.
+Override global semantic tokens first: colour roles, radius, spacing and density,
+typography, and control geometry. Component-level variables are implementation detail
+unless the module reference describes one as an extension point. Do not target hashed CSS
+Module names; use the stable `data-slot` attributes and BEM hooks such as
+`{name}--component`, and for a state the attributes the primitives set (`data-open`, `data-checked`, `data-disabled`,
+`data-highlighted`, `data-popup-open`). Radix's `[data-state="open"]` matches nothing here.
 
 ## Rich text and untrusted HTML
 
-`RichTextEditor` and editor engines keep drafts unsanitized. Render stored HTML with
-`RichText`, which always sanitizes through an allow-list. Any application-owned
-`dangerouslySetInnerHTML` remains the application's responsibility; see `SECURITY.md` in the
-package root.
+`RichTextEditor` and its engines keep drafts unsanitised. Render stored HTML with `RichText`,
+which always sanitises it through a fixed allow-list. Any `dangerouslySetInnerHTML` of your
+own is your application's responsibility; see [SECURITY.md](../../SECURITY.md).

package/docs/learn/verification.md

@@ -1,16 +1,16 @@
 # Verifying a consuming application
 
-The package is verified before it ships. Routing, data, permissions, copy and theme
-overrides belong to the application, so it still needs a small matrix of its own.
+Routing, data, permissions, copy and theme overrides belong to the application, so the
+application needs a small test matrix of its own.
 
 ## Minimum release checks
 
 1. Type-check against the installed package, not a source alias.
-2. Build the production bundle and confirm no optional peer is requested by unused families.
-3. Render every adopted family in light and dark themes.
+2. Build the production bundle and confirm no optional peer is requested by unused modules.
+3. Render every adopted module in light and dark themes.
 4. Exercise compact and comfortable density, plus any custom scale used by the product.
 5. Test keyboard traversal, focus return, dismissal, disabled state, loading state, and
-   destructive confirmations for interactive families.
+   destructive confirmations for interactive modules.
 6. Run automated accessibility checks, then manually verify names, descriptions, focus
    order, landmarks, and screen-reader announcements for the product composition.
 7. Check narrow mobile, ordinary desktop, and one wide viewport; include long translated
@@ -39,11 +39,11 @@ matches nothing.
 
 Create one application fixture that changes primary colour, surface/background roles,
 radius, density, and typography scale at a scope boundary. If a component ignores it, report
-the family and token before adding a local patch: the package may be missing a derivation.
+the module and token before adding a local patch: the package may be missing a derivation.
 
 ## Upgrade check
 
-Read `CHANGELOG.md`, run the package's codemod when a release names one
+Read the [changelog](../../CHANGELOG.md), run the package's codemod when a release names one
 (`node node_modules/themelia-ui/scripts/consumer/codemod.mjs --dry-run src/`), and let the
 application's own type-check compare the installed declarations. Within a major, a removal
 keeps a deprecated alias until the next major unless keeping it would be unsafe or