themelia-ui 3.0.0 → 3.2.0

package/docs/learn/theming.md

@@ -1,146 +1,192 @@
 # Theming
 
-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.
-
-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.
+The theme is about eighty variables, declared once at `:root` in `src/styles/theme/`. Each
+colour holds both modes as `light-dark(light, dark)`, and every length, shadow, tint and
+duration comes as a pair. Components derive everything else where they use it, so a value
+you set on a region reaches its descendants unless another scope or preset overrides it.
+[`src/styles/TOKENS.md`](../../src/styles/TOKENS.md)
+names the variable for each role.
 
 ## Setting a theme
 
-Where an override has to be declared depends on the kind of token.
-
-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:
+Set the variables you change on `:root`. A colour takes a `light-dark()` pair, or one value
+for both modes:
 
 ```css
 :root {
-  --brand-600: oklch(0.55 0.19 250);
-  --brand-350: oklch(0.72 0.14 250);
-  --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));
+  --radius: 0.75rem;
+  --radius-sm: 0.375rem;
+  --font-sans: "Your interface font", sans-serif;
 }
 ```
 
-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>`:
+That one block reaches every region, including popups portalled to `<body>` and a dark
+region inside a light page. Component styles do not redeclare theme colour defaults;
+an explicit regional theme override takes precedence within that region.
+
+The same values work on any element, for a region of their own:
 
 ```css
-:root, [data-ui-scope], [data-density], [data-theme], .light, .dark {
-  --primary: oklch(0.55 0.19 250);
+.marketing {
+  --primary: oklch(0.6 0.2 30);
 }
 ```
 
-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 them as config and writes them on its own element:
+
+```tsx fragment — shape only, not a program
+<UIProvider config={{ theme: { colors: { primary: "light-dark(#2563eb, #60a5fa)" } } }}>
+```
+
+Colours passed this way reach the provider's subtree. A popup portalled to `<body>` leaves
+that subtree; render it into the provider with `UIPortalHost` (see
+[Provider and scoping](./provider-and-scoping.md#portals-and-scopes)), or set the value on
+`:root` instead.
 
-A provider takes the same values as config and writes them on its own element:
+## Ready-made themes
+
+Four themes ship with the kit, each a style rather than a colour: Soft (large corners,
+diffuse shadows, comfortable spacing), Sharp (square corners, hairlines, no shadows), Dense
+(compact spacing and small corners, for data) and Editorial (serif headings on warm paper, a
+step larger type). Each is a `ThemePreset`: a `label`, a `description`, and the provider
+`config` it sets. That config reaches past colour to radii, shadows and border weight, density,
+typography, motion and component defaults, such as the card surface. Every theme's colours
+hold WCAG AA contrast in both modes, as the kit's own do.
 
 ```tsx fragment — shape only, not a program
-<UIProvider config={{ theme: { colors: { primary: "oklch(0.55 0.19 250)" } } }}>
+import { themes } from "themelia-ui/theming"
+
+<UIProvider config={themes.sharp.config}>
+```
+
+Switching themes is handing the provider another theme's config. Keep the choice in state,
+and wrap the application in `UIPortalHost`, so menus and popovers, which portal to `<body>`,
+take the theme too:
+
+```tsx fragment — shape only, not a program
+const [name, setName] = useState<ThemeName>("soft")
+
+<UIProvider config={themes[name].config}>
+  <UIPortalHost>
+    <App onThemeChange={setName} />
+  </UIPortalHost>
+</UIProvider>
 ```
 
-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.
+A nested provider themes one region the same way. Settings of your own go beside a theme's:
+`config={{ ...themes.dense.config, formatting: { locale: "de-DE" } }}`.
 
-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.
+A theme of your own is the same shape. Start from one of these and change what you need:
+
+```tsx fragment — shape only, not a program
+const brand: ThemePreset = {
+  label: "Brand",
+  description: "Our product's look.",
+  config: {
+    ...themes.sharp.config,
+    density: "comfortable",
+    theme: {
+      ...themes.sharp.config.theme,
+      colors: {
+        ...themes.sharp.config.theme?.colors,
+        primary: "light-dark(oklch(0.5 0.19 15), oklch(0.76 0.13 15))",
+        "primary-foreground": "light-dark(oklch(0.985 0 0), oklch(0.2 0.05 15))",
+      },
+    },
+  },
+}
+```
+
+A square theme should set `defaults.card.surface` to `"card"`: the default `framed` surface is
+a band that follows the corner, and with no corner to follow it reads as a box in a box. Write
+a zero radius as `0px`: the kit subtracts lengths from the radii, and `calc()` cannot subtract
+a length from a bare `0`. Write no shadow as `0 0 transparent`, not `none`: a popup lists
+`--shadow-lg` after its hairline, and `none` cannot stand in a list, so the popup would lose
+its edge.
+
+To edit a theme's colours and variables visually, load them into the theme editor with
+`themeFromConfig(themes.soft.config.theme)` from `themelia-ui/features/theme-tweaker`; the
+editor exports the result as CSS or provider config.
 
 ## Start with the shared controls
 
-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:
+Most adjustments need only these, and they follow a component's role rather than its name:
 
 ```css
 :root {
-  --surface-x: 1.25rem;
-  --surface-y: 1rem;
-  --row-x: 0.75rem;
-  --row-y: 0.5rem;
-  --font-sans: "Your interface font", sans-serif;
-  --radius: 0.75rem;    /* containers */
-  --radius-sm: 0.375rem; /* what sits inside them — set both, nothing derives it */
+  --padding: 1.25rem;      /* container insets: cards, dialogs, sheets, popovers */
+  --padding-sm: 0.625rem;  /* item insets: rows, cells, chips, fields */
+  --gap: 1.25rem;          /* between groups: fields, cards, sections */
+  --gap-sm: 0.625rem;      /* inside a group: icon and label, title and description */
+  --control-height: 2.25rem;
+  --radius: 0.75rem;       /* containers */
+  --radius-sm: 0.375rem;   /* what sits inside them; nothing derives one from the other */
 }
 ```
 
-- 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.
-- Menus and option lists inset their rows by `--space-md`, the difference between the two
-  radii, so rows sit concentric.
-- Dark mode inherits the chosen fonts.
+- A nested corner is the container's radius less its inset, computed where it is used, so
+  menus and option lists keep their rows concentric at any radius.
+- A density preset sets the four lengths and the two control heights on its region (see
+  [Scale and density](#scale-and-density)); a value you set on `:root` applies where no preset
+  is in effect.
 
 **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.
+`--font-mono` to its own fonts downloads none of them. `--font-heading` is unset by default,
+and headings fall back to the interface font.
 
 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.
+See [Structure and spacing](./structure-and-spacing.md) for the owner and responsive-width
+contracts before changing layout values.
 
-## Scale
+## Scale and density
 
-Three factors, and no per-module ones:
+Controls take two sizes, `default` and `sm`. A denser or roomier region is a scope instead,
+so everything inside it moves together:
 
-| Factor | Multiplies |
-|---|---|
-| `--scale` | everything; the other two default to it |
-| `--density-scale` | spacing, control heights and row rhythm, rounded to whole pixels |
-| `--text-scale` | the type scale, control labels included |
+| Setting | Moves |
+| --- | --- |
+| `density` | the four lengths and the two control heights; type keeps its size |
+| `scale` | the same, the two icon sizes, and type |
+| `typography.scale` | type alone, through `--text-scale` |
 
-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 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 `scale` when the
-whole scoped UI should move together.
+```tsx fragment — shape only, not a program
+<UIProvider config={{ density: "compact" }}>
+<UIProvider config={{ scale: 1.125 }}>
+<UIProvider config={{ typography: { scale: 0.875 } }}>
+```
 
-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.
+The provider computes `scale` in JavaScript and writes the lengths themselves, rounded to
+whole pixels, so no length is multiplied twice. A density preset also works without a
+provider: any element can carry `data-density="compact"` or `"comfortable"`.
 
-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.
+A preset sets its lengths on the region. To change a length under one preset, set it for
+that preset: `[data-density="compact"] { --padding: 0.625rem; }`.
 
 ## Dark mode
 
-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 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.
+Colours switch through `color-scheme`, which the kit sets from three signals: a `.dark` or
+`.light` class, `data-theme="dark"` or `"light"`, and, with neither, the operating system's
+preference. Each colour's `light-dark()` pair resolves on the element that paints it, so a
+dark region inside a light page needs only `data-theme="dark"` (or a nested provider with
+`colorScheme: "dark"`) on its container, and a light island inside a dark page the same.
 
-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.
+A value of your own switches the same way: write `light-dark()` in the value, never a rule
+under `.dark` or `@media (prefers-color-scheme: dark)`, which would miss a dark region inside
+a light page.
 
 ## 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.
+The exported stylesheet is one `:root` block in which each colour it changed is a
+`light-dark()` pair.
 
 The application owns the theme and provider state, above its router:
 
@@ -155,7 +201,6 @@ 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())
@@ -195,10 +240,11 @@ const overrides = deriveThemePalette({ primary: "#3b82f6" })
 // { "--primary": "#3b82f6", "--primary-foreground": "oklch(0.18 0.01 260)", … }
 ```
 
-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.
+The keys are theme variables, so write them on `:root` 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 variables they derive from.
+Derive one set for each mode and pair them, as the ThemeTweaker does, when the two should
+differ.
 
 `readableForeground(background)` **measures** WCAG contrast against both candidates and
 returns the better one, with the ratio and whether it clears AA:
@@ -215,64 +261,61 @@ Both functions are also re-exported from `features/theme-tweaker`.
 
 ## Design tokens (DTCG)
 
-`themelia-ui/tokens.json` is the contract in [W3C DTCG][dtcg] format, for Figma and
-tools like Style Dictionary. Colours are OKLCH objects with a `hex` fallback:
+`themelia-ui/tokens.json` is the theme in [W3C DTCG][dtcg] format, for Figma and tools like
+Style Dictionary. Each colour is a token in `theme.light` and one in `theme.dark`; every other
+variable is written once in `theme.light` and aliased from `theme.dark`. Colours are OKLCH
+objects with a `hex` fallback:
 
 ```json
 { "$value": { "colorSpace": "oklch", "components": [0.45, 0.124, 167.35], "hex": "#006a47" } }
 ```
 
-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
-  would bake one theme's ink in.
+Shadows, durations, the easing curve and the font stacks carry their DTCG types. The two tint
+strengths are percentages, which DTCG cannot express, and the unset font roles have no value;
+the file lists them under its `$extensions`.
 
 [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 after Tailwind and the kit's stylesheet, and its utilities resolve against
-this contract:
+import the bridge after Tailwind, and its utilities resolve against the theme:
 
 ```css
 @import "tailwindcss";
-@import "themelia-ui/core.css";
 @import "themelia-ui/tailwind.css";
 ```
 
-`bg-primary` is `var(--primary)`, `rounded-sm` is the kit's inner radius, `p-md` is
-`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 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:
+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.
+
+`bg-primary` is `var(--primary)`, `rounded` is the container radius and `rounded-sm` the
+item radius, `p-padding` and `gap-gap-sm` are the kit's lengths, and `text-sm` is
+`calc(0.875rem * var(--text-scale))`, which follows the type factor as Text does. Every
+utility reads the variable **at the element**, so a dark region, 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 the bridge even if you never write a kit utility.** Both projects descend from
+shadcn, so custom-property names collide: `--radius`, `--radius-sm`, `--shadow`,
+`--shadow-lg`, `--text-xs` through `--text-2xl` and the font stacks. Tailwind emits its
+defaults onto `:root` inside `@layer theme`, and depending on the order your application
+imports its CSS, that layer can sit above the kit's `tokens` layer. Without the bridge,
+Tailwind can win every shared name:
 
 | 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`, and **scoped type scaling stops working** |
+| `--radius-sm` | `0.5rem`, the kit's item radius | `0.25rem` |
+| `--shadow-lg` | the kit's floating shadow | Tailwind's `shadow-lg` |
 | `--font-sans` | Geist first | Tailwind's system stack |
-| `--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 in either order. It is generated from the same public tokens.
+The symptom is a slightly wrong radius or shadow, not an error. The bridge restates those
+names with the kit's own values, so Tailwind's override becomes a no-op in either order. It is
+generated from the theme. The kit declares nothing in Tailwind's `--animate-*` namespace, so
+`animate-spin` and its neighbours stay Tailwind's own.
 
-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
-a kit token or a formula are `@theme inline`, so they resolve at the element; the restated
-literals (the inner radius, font stacks, leading, easing) are a plain `@theme`, so their
-utilities read the variable and follow a theme that moves it.
+The bridge is 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 a kit
+variable or a formula are `@theme inline`, so they resolve at the element; the restated
+literals (the radii, shadows and font stacks) are a plain `@theme`, so their utilities read
+the variable and follow a theme that moves it.

package/docs/learn/troubleshooting.md

@@ -1,10 +1,37 @@
 # Troubleshooting
 
+Before patching a shared component, trace its callers and inspect one representative of
+every affected surface. Recheck open portals, nested forms and small screens when shared
+spacing or naming changes. Use the [read-only diagnosis and completion record](./verification.md)
+to distinguish contract errors, advisory composition findings and unavailable coverage.
+
+## A lookup still shows another workspace
+
+Set `scopeKey` on ResourceCombobox, SuggestionsCombobox or useSuggestions. Callback identity is not an invalidation API.
+The key invalidates answers and errors while keeping query/open/value ownership; explicitly
+clear a selected id if it is invalid in the new scope. See the [complete selector](./reference-workflows.md).
+
+## Validation resolves but the dialog closes
+
+Set `closeOnAsyncComplete={false}` and close controlled `open` after successful validation
+and mutation. Use `formId` for native submission and keep one mutation owner. Nested child
+cancel/Escape should leave the parent draft visible; verify focus returns to the child invoker.
+
 ## A component is unstyled
 
-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).
+A component brings its own CSS in a bundler. When it arrives unstyled:
+
+- **Server rendering with Vite** (Astro, React Router, TanStack Start, Vike): add
+  `themelia-ui`, and any installed package that imports it, to `ssr.noExternal`. See
+  [Server rendering with Vite](./installation.md#server-rendering-with-vite).
+- **Parcel:** set `"@parcel/resolver-default": { "packageExports": true }`.
+- **Custom resolve conditions:** a bundler config that sets its own conditions replaces the
+  defaults, and the kit's CSS resolves only under `module`. Keep it: in Vite 6 or later,
+  spread `defaultClientConditions` into `resolve.conditions` and `defaultServerConditions`
+  into `ssr.resolve.conditions` (both exported from `vite`); in esbuild, add `module` to
+  `conditions`.
+- **No bundler:** link `style.css`. See
+  [Loading the CSS](./installation.md#loading-the-css).
 
 Overrides need no `!important` or selector escalation: the kit's rules are layered, and
 unlayered application CSS beats them.
@@ -12,15 +39,36 @@ 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.
+that imports a stylesheet, without a bundler. The kit's own CSS imports resolve to an empty
+module in Node. Import your 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).
 
+## Jest: `Cannot find module '#core.css'`
+
+Jest resolves the package's `imports` map from 29.4 onwards. Upgrade Jest.
+
+## A build fails on a `.css` file
+
+A bundler that resolves the package's `module` condition bundles its CSS as well. A server
+build with no CSS handling, such as a webpack or Rollup config without a CSS loader, fails on
+it. Leave the package external in that build, so Node loads it with no CSS, or add a loader
+that ignores `.css`. A client build needs a CSS loader too; with one in place, remove any
+`<link>` to a kit stylesheet, since the CSS now arrives with the components.
+
+## The kit's CSS loads twice
+
+Components bring their own CSS, so an application that also imports `themelia-ui/style.css`
+or a module stylesheet from JavaScript, or `@import`s one into its own CSS, ships the same
+rules twice. Remove those imports: the upgrade codemod removes the JavaScript ones and lists
+the rest. A JavaScript import of `themelia-ui/core.css` is harmless, since bundlers keep one
+copy. A page whose JavaScript is bundled that also links a kit stylesheet with an HTML
+`<link>` loads it twice as well; remove the `<link>`.
+
 ## A subpath does not resolve
 
 There are no tier barrels such as `themelia-ui/base`. Use the generated
@@ -30,7 +78,10 @@ There are no tier barrels such as `themelia-ui/base`. Use the generated
 node node_modules/themelia-ui/scripts/consumer/find-component.mjs "what the UI must do"
 ```
 
-Import the returned exact module path and its returned CSS path.
+Import the returned module path; in a bundled app its CSS comes with it.
+
+Parcel reads a package's `exports` only with `"@parcel/resolver-default": { "packageExports":
+true }` in the application's `package.json`.
 
 ## An optional peer is missing
 
@@ -40,23 +91,20 @@ listed there, report it as a package containment defect.
 
 ## 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`.
+Theme defaults are declared at `:root` and inherit until an explicit scope override or
+density preset establishes another value. When an override does not show:
+
+- **Is it the theme's name?** A 3.0 name such as `--space-md`, `--control-h` or
+  `--primary-10` is gone; the codemod renames or reports each one, and
+  [`src/styles/TOKENS.md`](../../src/styles/TOKENS.md) names the variable for every role.
+- **Is a density preset in effect?** A `data-density` region (or a provider's `density`) sets
+  the lengths and control heights on its element, so a value set further out does not reach
+  inside it. Set the value for the preset too: `[data-density="compact"] { --padding: … }`.
+- **Is it a colour set to one value?** One value applies in both modes. For a separate dark
+  value, write `light-dark(light, dark)`; a rule under `.dark` misses a dark region inside a
+  light page.
+- **Is it in a portalled popup?** A value set on a provider or a region reaches its subtree,
+  and a popup portalled to `<body>` leaves it; see the next section.
 
 See [Theming](./theming.md#setting-a-theme) and
 [Provider and scoping](./provider-and-scoping.md).
@@ -66,8 +114,8 @@ See [Theming](./theming.md#setting-a-theme) and
 Popups portal to `<body>` by default, outside any nested scope, so they miss its density,
 colour scheme and token overrides. Wrap the region in `UIPortalHost` so its popups render
 inside the scope, or pass the component a `container`. A root provider with a
-`documentTarget` mirrors only `data-theme` and `data-density` to the document; token
-overrides that `<body>` popups must see belong in CSS at the scope boundaries. See
+`documentTarget` mirrors only `data-theme` and `data-density` to the document; a value that
+`<body>` popups must see belongs on `:root`. See
 [Provider and scoping](./provider-and-scoping.md#portals-and-scopes).
 
 ## A controlled component appears frozen
@@ -87,17 +135,27 @@ 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. The module stylesheets themselves are ordinary static CSS. See
+stylesheet. The kit's stylesheets are ordinary static CSS. See
 [Provider and scoping](./provider-and-scoping.md#strict-content-security-policy).
 
+If the report names `style-src-attr`, a nonce or `disableStyleElements` will not authorize
+server-rendered style attributes. Inspect the adopted components' SSR output and use the
+separate attribute-policy strategy described in that guide.
+
+In a bundled app the kit's CSS follows your own pipeline: stylesheet files in production,
+while a dev server or `style-loader` that injects `<style>` elements needs the nonce, as your
+own CSS does.
+
 ## The design looks inconsistent after overrides
 
 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
+typography, and control geometry. Variables prefixed `--_` are private implementation detail.
+Use a component-level variable only when its module reference documents a public 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.
+`data-highlighted`, `data-popup-open`). Do not assume Radix's `[data-state="open"]` for Base
+UI primitives. Use a module's own `data-state` only when its API documents that contract.
 
 ## Rich text and untrusted HTML