@c15t/react 3.0.0-alpha.8 → 3.0.0-alpha.9

package/dist-types/ui-config-context.d.ts

@@ -12,6 +12,10 @@ export interface V3UIConfigValue {
     theme?: Theme;
     legalLinks?: LegalLinks;
     preloadDialog?: DialogPreload;
+    /** CSP nonce for the `<style>` elements the surfaces render. */
+    nonce?: string;
+    /** `false` when the app loads `styles.css` itself. */
+    styles?: boolean;
 }
 export declare const V3UIConfigContext: import("react").Context<V3UIConfigValue>;
 export declare const useUIConfig: () => V3UIConfigValue;

package/dist-types/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.0.0-alpha.8";
+export declare const version = "3.0.0-alpha.9";

package/docs/README.md

@@ -36,7 +36,7 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [DevTools](./frameworks/react/components/dev-tools.md): Inspect consent state, location, loaded scripts and consent events in a React app during development with the c15t DevTools panel.
 - [Compose your own banner](./frameworks/react/compose.md): Build a React consent banner from the ConsentBanner parts in c15t/react, with your own markup and buttons, while the policy still decides which actions appear.
 - [Content Security Policy](./frameworks/react/content-security-policy.md): Run c15t in a React app under a Content Security Policy, allow the consent backend and vendor hosts, and pass a nonce to ConsentProvider and ConsentTheme.
-- [Customize](./frameworks/react/customize.md): Change the colors, fonts, layout, button styles and copy of the c15t banner and dialog in a React app with the stylesheet, theme tokens, provider options and slots.
+- [Customize](./frameworks/react/customize.md): Change the colors, fonts, layout, button styles and copy of the c15t banner and dialog in a React app with theme tokens, provider options and slots, and load the stylesheet yourself when you need to.
 - [Embeds](./frameworks/react/embeds.md): Keep YouTube videos, maps and other iframes out of a React page until their consent category is allowed, with ConsentGate or the iframe blocker in ConsentProvider.
 - [IAB GPP](./frameworks/react/gpp.md): Add the IAB Global Privacy Platform API (__gpp) to a React app with ConsentGPP from @c15t/react/gpp, so ad tech can read US state opt-outs and the TCF EU consent string.
 - [Headless](./frameworks/react/headless.md): Build a custom consent banner in React with the c15t/react/headless hooks inside your ConsentProvider.
@@ -74,8 +74,8 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [Customize the interface](./customization/overview.md): Change c15t's consent banner and dialog one step at a time, from a prop to your own markup, and find where each step lives in your framework.
 - [Banner designs](./customization/recipes.md): Five consent banner designs built with c15t, from one prop to your own markup, with tested code for React, Vue, Svelte, Astro and plain HTML.
 - [Component parts](./customization/slots.md): Find every part of c15t's banner, dialog, widget, trigger and ConsentGate placeholder, its key in your framework's part API, and the data attributes to select on.
-- [Stylesheets and CSS layers](./customization/stylesheets.md): Load the right c15t stylesheet for your framework, see which file holds the dialog's rules, order c15t's cascade layer against your own, and run c15t without its styles.
-- [Tailwind CSS](./customization/tailwind.md): Load c15t's styles next to Tailwind CSS 4 or 3 in every framework, put utilities on c15t component parts, and use Tailwind's dark variant with c15t.
+- [Stylesheets and CSS layers](./customization/stylesheets.md): See how c15t delivers its styles in each framework without a render-blocking stylesheet, when to import styles.css yourself with styles false, which file holds the dialog's rules, and how c15t's cascade layer meets your own.
+- [Tailwind CSS](./customization/tailwind.md): Use c15t's styles with Tailwind CSS 4 or 3 in every framework, put utilities on c15t component parts, and use Tailwind's dark variant with c15t.
 - [Theme tokens](./customization/tokens.md): Change c15t's colors, type, radius, spacing, shadows and motion with theme tokens, and see every --c15t-* variable with its default.
 - [Copy and translations](./customization/translations.md): Change consent wording through i18n and test the complete prompt and preferences flow.
 

package/docs/concepts/choose-your-setup.md

@@ -88,7 +88,9 @@ The snapshot is fixed at build time:
 
 * Rebuild after changing policies, translations or vendors. If your CI caches
   build output, force a fresh build.
-* The build must reach the backend. A failed fetch fails the build.
+* The build must reach the backend. A failed fetch stops Next.js, TanStack
+  Start, SvelteKit and Vite builds. By default, Astro and Nuxt log a warning
+  instead and fetch the policy at runtime.
 * Consent choices still go to the backend.
 
 For deployments that need policy updates without a rebuild, choose a runtime

package/docs/concepts/data-fetching.md

@@ -55,7 +55,9 @@ The snapshot is fixed at build time:
 
 * Rebuild after changing policies, translations or vendors. If your CI caches
   build output, force a fresh build.
-* The build must reach the backend. A failed fetch fails the build.
+* The build must reach the backend. A failed fetch stops Next.js, TanStack
+  Start, SvelteKit and Vite builds. By default, Astro and Nuxt log a warning
+  instead and fetch the policy at runtime.
 * Consent choices still go to the backend.
 
 ## How manifest mode counts visitors

package/docs/customization/overview.md

@@ -67,8 +67,9 @@ policy requires, c15t puts it back.
   dark first paint.
 * [Motion and animation](./motion.md): duration and easing
   tokens, `disableAnimation` and reduced motion.
-* [Stylesheets and CSS layers](./stylesheets.md): which file to
-  load, when the dialog's CSS loads, and how to run without c15t's styles.
+* [Stylesheets and CSS layers](./stylesheets.md): how c15t
+  loads its rules, when to import `styles.css` yourself, when the dialog's CSS
+  loads, and how to run without c15t's styles.
 * [Component parts](./slots.md): every part, its keys in each
   framework, and the `data-*` attributes to select on.
 * [Class names and CSS-in-JS](./class-names.md): CSS Modules,

package/docs/customization/stylesheets.md

@@ -1,45 +1,145 @@
 ---
 title: Stylesheets and CSS layers
-description: Load the right c15t stylesheet for your framework, see which file
-  holds the dialog's rules, order c15t's cascade layer against your own, and run
-  c15t without its styles.
+description: See how c15t delivers its styles in each framework without a
+  render-blocking stylesheet, when to import styles.css yourself with styles
+  false, which file holds the dialog's rules, and how c15t's cascade layer meets
+  your own.
 group: customization
 ---
 
-## Load one stylesheet for your framework
-
-| Framework         | What to load                     | Where                                                                |
-| ----------------- | -------------------------------- | -------------------------------------------------------------------- |
-| Next.js           | `c15t/next/styles.css`           | Your global stylesheet, or the layout that renders the consent root  |
-| TanStack Start    | `c15t/tanstack-start/styles.css` | A `<link>` from the root route's `head()`, or your global stylesheet |
-| React             | `c15t/react/styles.css`          | The module that renders `ConsentProvider`, or your global stylesheet |
-| Nuxt, Vue         | Nothing                          | Each Vue component imports its own stylesheet                        |
-| Astro             | Nothing                          | The integration adds `c15t/astro/styles.css` to every page           |
-| Svelte, SvelteKit | `@c15t/svelte/styles.css`        | Your entry module or root layout                                     |
-| HTML              | Nothing                          | `c15t.js` carries its stylesheet into the UI's shadow root           |
-| JavaScript        | Nothing                          | `init()` carries its stylesheet into the UI's shadow root            |
-
-Load it once. With IAB TCF in Next.js, TanStack Start, React, Svelte or
-SvelteKit, also load the adapter's `iab/styles.css`, such as
-`c15t/next/iab/styles.css`, after `styles.css`. Astro adds its IAB stylesheet
-when the integration sets `iab`. Tailwind 3 uses the same files and adds a
-PostCSS plugin; [Tailwind CSS](./tailwind.md#set-up-tailwind-css-3)
-shows the setup.
+## What each framework loads
+
+| Framework                      | What you import | How the styles arrive                                                                                                                                                                                                     |
+| ------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Next.js, TanStack Start, React | Nothing         | Each stock surface renders the rules it uses as `<style>` elements                                                                                                                                                        |
+| Nuxt, Vue                      | Nothing         | Each Vue component imports its own stylesheet                                                                                                                                                                             |
+| Astro                          | Nothing         | `<ConsentScript />` inlines the banner's rules into the HTML. The client links the dialog's rules when a dialog first opens. On a Tailwind CSS 3 site, the integration adds `c15t/astro/styles.css` to every page instead |
+| Svelte                         | Nothing         | Each stock surface inserts the rules it uses into `<head>`                                                                                                                                                                |
+| SvelteKit                      | Nothing         | `c15tHandle` writes a server-rendered banner's rules into the HTML. The other surfaces insert theirs in the browser                                                                                                       |
+| HTML                           | Nothing         | `c15t.js` carries its stylesheet into the UI's shadow root                                                                                                                                                                |
+| JavaScript                     | Nothing         | `init()` carries its stylesheet into the UI's shadow root                                                                                                                                                                 |
+
+Inline c15t styles avoid a stylesheet request before the page's first paint.
+A linked stylesheet in `<head>` used to delay it by a round trip. With 4x
+CPU throttling, 1.6 Mbps download and 150 ms RTT, a Next.js page first painted
+at about 370 ms instead of 650 ms once the link was gone.
+
+Inline rules add bytes to each server-rendered HTML response. Enable HTTP
+compression on the production host to reduce their transfer cost. On repeat
+document visits, a cached external stylesheet can paint sooner than sending
+the inline rules again. To use that cache, keep the stylesheet imports and
+set `styles: false` as described below.
+
+Load `styles.css` yourself with Tailwind CSS 3 or a named cascade layer.
+[Import the stylesheet yourself](#import-the-stylesheet-yourself)
+covers those cases.
+
+## How the surfaces deliver their rules
+
+c15t splits its rules into two sheets. The first-paint sheet holds the
+default tokens, every c15t CSS variable, and the rules for the banner, the
+floating trigger and the `ConsentGate` placeholder. The dialog sheet holds the
+preference dialog's and the preference widget's rules.
+
+In React, Next.js and TanStack Start, `ConsentBanner`, `ConsentDialogTrigger`
+and the default `ConsentGate` placeholder render the first-paint sheet.
+`ConsentDialog` and `ConsentWidget` render it plus the dialog sheet. The
+dialog sheet ships with the dialog's lazily loaded code, so it is not part of
+the first page load. A server-rendered banner puts its rules in the HTML.
+
+`IABConsentBanner` also delivers the IAB variables and banner rules.
+`IABConsentDialog` adds the IAB dialog rules when it opens, including the
+shared rules it needs when rendered without a banner. IAB setups need no
+stylesheet imports with automatic styling enabled.
+
+Streamed React IAB banners become visible once their complete card markup
+arrives. This prevents the centered card from moving as the browser parses
+its remaining content, without waiting for hydration.
+
+* In React 19, React moves the elements into `<head>` and renders each sheet
+  once per page, as `<style data-precedence="c15t" data-href="c15t-first-paint">`.
+* In React 18, the elements render in place, next to the surface.
+* In React 19 with the provider's `nonce` option set, they also render in
+  place and carry the nonce. React drops the nonce of a style it moves to
+  `<head>` unless the app passed that nonce to React's server renderer.
+
+In Svelte, each stock surface inserts the sheets it uses into `<head>` as
+`<style data-c15t-styles="…">`, once per page, before its own elements
+render. The elements stay after the surface unmounts. The Svelte dialog's
+sheets, its rules and the primitives, load with the dialog's code.
+
+On a server-rendered SvelteKit page, the banner leaves a
+`<meta name="c15t-styles">` marker, and `c15tHandle` from `@c15t/svelte/kit`
+writes the sheets into the HTML `<head>` as `<style>` elements. The banner is
+styled before hydration with no stylesheet request. Without `c15tHandle` in
+`src/hooks.server.ts`, a server-rendered banner shows unstyled until
+hydration. The [SvelteKit quickstart](https://c15t.com/docs/frameworks/sveltekit/quickstart)
+adds the handle.
+
+In Astro, `<ConsentScript />`, or the banner on a layout without it, inlines
+the first-paint sheet into the HTML as
+`<style data-c15t-styles="c15t-first-paint">` with the page nonce. When
+`tailwindcss` resolves to version 3 from the Astro root, the integration
+inlines nothing and adds `c15t/astro/styles.css` to every page through
+Astro's CSS pipeline, so the site's `c15t/postcss-tailwind3` plugin processes
+it. That stylesheet still holds back the first paint.
+
+The surfaces render no stylesheet with `noStyle`, or when the provider sets
+`styles: false`.
+
+## Import the stylesheet yourself
+
+Set `styles: false` in the provider options and import `styles.css` when you
+need control over the file:
+
+* **Tailwind CSS 3.** c15t's `<style>` rules sit in a native
+  `@layer components`, and Tailwind 3's unlayered preflight beats them. Import
+  `styles.css` through the `postcss-tailwind3` plugin instead, as
+  [Tailwind CSS](./tailwind.md#set-up-tailwind-css-3) shows.
+  Astro sites skip this: the integration detects Tailwind 3 and links the
+  stylesheet itself.
+* **A named cascade layer.** Import the stylesheet into your own layer, as in
+  [order c15t's layer against your CSS](#order-c15ts-layer-against-your-css).
+* **Cached styles across document visits.** Keep external CSS when its HTTP
+  cache performs better for your site's repeat visits. Compare cold and warm
+  visits on your production host before choosing this option.
+
+| Framework         | Option                                       | Files to import                                                                        |
+| ----------------- | -------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Next.js           | `options.styles` on `ConsentRoot`            | `c15t/next/styles.css`, and `c15t/next/iab/styles.css` for IAB TCF                     |
+| TanStack Start    | `options.styles` on `ConsentRoot`            | `c15t/tanstack-start/styles.css`, and `c15t/tanstack-start/iab/styles.css` for IAB TCF |
+| React             | `options.styles` on `ConsentProvider`        | `c15t/react/styles.css`, and `c15t/react/iab/styles.css` for IAB TCF                   |
+| Svelte, SvelteKit | `options.styles` on `ConsentManagerProvider` | `@c15t/svelte/styles.css`, and `@c15t/svelte/iab/styles.css` for IAB TCF               |
+| Astro             | `styles` in the `c15t()` integration options | See [load Astro's stylesheets yourself](#load-astros-stylesheets-yourself)             |
+
+```tsx title="components/consent.tsx (partial)"
+<ConsentRoot
+	state={state}
+	config={consentConfig}
+	options={{ styles: false }}
+>
+```
+
+`styles: false` turns off only the stylesheets. Tokens from `ConsentTheme`
+and slot classes still apply.
+
+If you keep a `styles.css` import without `styles: false`, the surfaces still
+look right, but the rules ship twice and the stylesheet link still holds back
+the first paint. Remove the import, or add `styles: false` if you need it.
 
 ## Where the dialog's rules come from
 
-`styles.css` holds the default tokens, every c15t CSS variable and the rules
-for every stock surface: the banner, the floating trigger, the `ConsentGate`
-placeholder, the preference dialog and the preference widget. Only the IAB TCF
-surfaces need a second file, `iab/styles.css`.
+| Framework                      | The preference dialog's rules                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Next.js, TanStack Start, React | In the dialog sheet that `ConsentDialog` and `ConsentWidget` render. It ships with the dialog's lazily loaded code. With `styles: false`, in `styles.css`. No `@c15t/react` or `@c15t/ui` module imports CSS, so a Next.js app that uses only the Pages Router builds without `transpilePackages`                                                                                                                                           |
+| Nuxt, Vue                      | The dialog component imports its stylesheet, so the rules load with the dialog's code, not the banner's                                                                                                                                                                                                                                                                                                                                     |
+| Astro                          | In `@c15t/ui/styles/sheets/dialog.css`. The Svelte dialog, the default `ui`, also needs the primitives stylesheet. c15t links both when a visitor first points at, focuses or opens a control that opens the dialog, waits for them before it shows the dialog, and keeps them across `ClientRouter` navigation. On a Tailwind CSS 3 site, the dialog's rules are in `c15t/astro/styles.css`, and c15t links only the primitives stylesheet |
+| Svelte, SvelteKit              | In the dialog's sheets, which load with the dialog's code. With `styles: false`, in `@c15t/svelte/styles.css`                                                                                                                                                                                                                                                                                                                               |
+| HTML, JavaScript               | Part of the stylesheet in the shadow root, which holds only the rules the stock surfaces use                                                                                                                                                                                                                                                                                                                                                |
 
-| Framework                      | The preference dialog's rules                                                                                                                                                                                                                        |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Next.js, TanStack Start, React | In `styles.css`. No `@c15t/react` or `@c15t/ui` module imports CSS, so a Next.js app that uses only the Pages Router builds without `transpilePackages`                                                                                              |
-| Nuxt, Vue                      | The dialog component imports its stylesheet, so the rules load with the dialog's code, not the banner's                                                                                                                                              |
-| Astro                          | In `c15t/astro/styles.css`. The Svelte dialog, the default `ui`, also needs the primitives stylesheet, which c15t links when a visitor first points at, focuses or opens a control that opens the dialog, and keeps across `ClientRouter` navigation |
-| Svelte, SvelteKit              | In `@c15t/svelte/styles.css`                                                                                                                                                                                                                         |
-| HTML, JavaScript               | Part of the stylesheet in the shadow root, which holds only the rules the stock surfaces use                                                                                                                                                         |
+`styles.css` still holds every stock surface's rules for apps that set
+`styles: false`. In that manual mode, IAB TCF also needs `iab/styles.css`
+after the base stylesheet.
 
 Earlier 3.0 alphas shipped the dialog's rules in `@c15t/ui/styles/dialog.css`,
 which the dialog's code imported. That file, the `@c15t/ui/styles/dialog`
@@ -49,8 +149,8 @@ imports keep resolving. Remove those imports.
 ## Order c15t's layer against your CSS
 
 c15t puts its component rules in the cascade layer `components`. Tokens,
-variables and keyframes stay unlayered. Each stylesheet opens with Tailwind
-CSS 4's layer order:
+variables and keyframes stay unlayered. Each stylesheet, and each `<style>`
+element the surfaces render, opens with Tailwind CSS 4's layer order:
 
 ```css
 @layer properties, theme, base, components, utilities;
@@ -71,18 +171,23 @@ What this means for your overrides:
   [theme tokens](./tokens.md).
 
 If your CSS declares its own layer order, load that statement before c15t's
-stylesheet. You can import c15t's stylesheet into a named layer, such as
+rules. To put c15t's rules in a named layer, set `styles: false` and import
+the stylesheet into that layer, such as
 `@import 'c15t/react/styles.css' layer(c15t)`. Its component rules then sit
 in `c15t.components`, so order `c15t` against your own layers.
 
 ## Load Astro's stylesheets yourself
 
-The Astro integration adds `c15t/astro/styles.css` to every page ahead of your
-own CSS. To control the order yourself, for example from a global stylesheet
-that names its own layers, set `styles: false` in the `c15t()` options and
-import the files after your layer order statement. With `styles: false`, c15t
-links no stylesheet when the dialog opens either. The Svelte dialog, the
-default `ui`, needs the primitives stylesheet next to `styles.css`:
+By default the Astro integration inlines the banner's rules into each page,
+including the IAB banner rules when it sets `iab`, and links the dialog's
+rules when a dialog opens. On a Tailwind CSS 3 site it adds
+`c15t/astro/styles.css` and, with IAB, `c15t/astro/iab/styles.css` to every
+page instead of inlining the banner's rules. To load the
+files yourself, for example from a global stylesheet that names its own
+layers, set `styles: false` in the `c15t()` options and import them after
+your layer order statement. With `styles: false`, c15t inlines no rules and
+links no stylesheet when the dialog opens. The Svelte dialog, the default
+`ui`, needs the primitives stylesheet next to `styles.css`:
 
 ```css title="src/styles/global.css"
 @import 'c15t/astro/styles.css';
@@ -92,9 +197,9 @@ default `ui`, needs the primitives stylesheet next to `styles.css`:
 @import 'c15t/astro/iab/styles.css';
 ```
 
-Keep c15t's stylesheet when you restyle the surfaces. The browser hides the
-Astro banner with the `hidden` attribute, and the stylesheet makes that
-attribute beat the banner's own `display` rule.
+Keep c15t's rules when you restyle the surfaces. The browser hides the Astro
+banner with the `hidden` attribute, and c15t's rules make that attribute beat
+the banner's own `display` rule.
 
 ## Style the script tag's shadow root
 
@@ -129,9 +234,17 @@ selector before you reach for `noStyle`.
 
 ## Check the result
 
-1. Open DevTools Network, clear site data and reload. Your framework's c15t
-   stylesheet loads once, and no second copy appears.
-2. Open the preference dialog. It is styled on its first frame, and in React,
-   Next.js and TanStack Start no new stylesheet request appears.
-3. Select a banner part and read the Styles panel. c15t's rules appear under
+1. Open DevTools Network, clear site data and reload. No c15t stylesheet
+   request appears before the first paint. In the HTML or the Elements panel,
+   `<head>` holds c15t's rules: `<style data-href="c15t-first-paint">` in
+   React 19, or a `<style data-c15t-styles>` element in Svelte, SvelteKit
+   and Astro. In React 18, or with a `nonce`, the `<style>` sits next to the
+   banner instead.
+2. Open the preference dialog. It is styled on its first frame. Opening it
+   adds the dialog's rules: a second `<style>` element in React, Next.js,
+   TanStack Start, Svelte and SvelteKit, or a linked
+   `@c15t/ui/styles/sheets/dialog.css` in Astro.
+3. With `styles: false`, your imported `styles.css` loads once, and no c15t
+   `<style>` element appears.
+4. Select a banner part and read the Styles panel. c15t's rules appear under
    `@layer components`, and your unlayered rules for the same property win.

package/docs/customization/tailwind.md

@@ -1,8 +1,7 @@
 ---
 title: Tailwind CSS
-description: Load c15t's styles next to Tailwind CSS 4 or 3 in every framework,
-  put utilities on c15t component parts, and use Tailwind's dark variant with
-  c15t.
+description: Use c15t's styles with Tailwind CSS 4 or 3 in every framework, put
+  utilities on c15t component parts, and use Tailwind's dark variant with c15t.
 group: customization
 ---
 
@@ -21,7 +20,10 @@ directive and fails the build on a stylesheet that uses it without a matching
 `@tailwind components`. c15t's Tailwind 3 PostCSS plugin removes the layer
 wrappers from c15t's stylesheets before Tailwind 3 runs. c15t's rules then
 win by specificity, as they did in c15t v2, so a utility on a c15t part needs
-Tailwind's important modifier, such as `!p-2`.
+Tailwind's important modifier, such as `!p-2`. The plugin cannot reach the
+`<style>` elements c15t renders itself, so on Tailwind 3 you turn those off
+with `styles: false` and import the stylesheet instead. The Astro integration
+does this for you when it finds Tailwind 3.
 
 The setups below come from fixtures that CI builds for each framework and
 checks in Chromium. The Next.js snippets come from the Next.js 16 Turbopack
@@ -34,9 +36,11 @@ without a backend, so they use `offline()` mode or a local `backendURL`. Keep th
 
 ## Set up Tailwind CSS 4
 
-Install Tailwind's plugin for your build tool, add it to the build, and load
-c15t's stylesheet in the same CSS entry as Tailwind. Vue, Nuxt and Astro load
-c15t's styles for you, so their CSS entry holds only Tailwind.
+Install Tailwind's plugin for your build tool and add it to the build. c15t
+loads its own styles in every framework, so your CSS entry holds only
+Tailwind. Do not import c15t's stylesheet next to Tailwind 4: the stock
+components already render the same rules, and the import would hold back the
+first paint.
 
 **Next.js**
 
@@ -46,20 +50,18 @@ Next.js runs Tailwind 4 through `@tailwindcss/postcss`:
 export default { plugins: { '@tailwindcss/postcss': {} } };
 ```
 
-Import c15t after Tailwind in the global stylesheet that `app/layout.tsx`
-or `pages/_app.tsx` loads:
+Import Tailwind in the global stylesheet that `app/layout.tsx` or
+`pages/_app.tsx` loads:
 
 ```css title="app/globals.css"
 @import 'tailwindcss';
-@import 'c15t/next/styles.css';
 
 @custom-variant dark (&:where(.dark, .dark *));
 ```
 
 **TanStack Start**
 
-Add `@tailwindcss/vite` before the TanStack Start plugin, then import
-Tailwind and c15t from the stylesheet your root route links:
+Add `@tailwindcss/vite` before the TanStack Start plugin:
 
 ```ts title="vite.config.ts"
 import tailwindcss from '@tailwindcss/vite';
@@ -76,11 +78,10 @@ export default defineConfig({
 });
 ```
 
-Import Tailwind and c15t from the stylesheet your root route links:
+Import Tailwind from the stylesheet your root route links:
 
 ```css title="src/styles.css"
 @import 'tailwindcss';
-@import 'c15t/tanstack-start/styles.css';
 
 @custom-variant dark (&:where(.dark, .dark *));
 ```
@@ -95,12 +96,10 @@ import { defineConfig } from 'vite';
 export default defineConfig({ plugins: [react(), tailwindcss()] });
 ```
 
-Import this stylesheet from your entry module in place of a separate
-`c15t/react/styles.css` import:
+Import this stylesheet from your entry module:
 
 ```css title="src/app.css"
 @import 'tailwindcss';
-@import 'c15t/react/styles.css';
 
 @custom-variant dark (&:where(.dark, .dark *));
 ```
@@ -155,8 +154,9 @@ Import this stylesheet from `src/main.ts`:
 
 **Astro**
 
-The integration adds `c15t/astro/styles.css` to every page, so the CSS
-entry holds only Tailwind. Add `@tailwindcss/vite` under `vite.plugins`:
+c15t inlines the banner's rules into each page and links the dialog's
+when it opens, so the CSS entry holds only Tailwind. Add
+`@tailwindcss/vite` under `vite.plugins`:
 
 ```js title="astro.config.mjs"
 import svelte from '@astrojs/svelte';
@@ -202,12 +202,10 @@ import { defineConfig } from 'vite';
 export default defineConfig({ plugins: [svelte(), tailwindcss()] });
 ```
 
-Import this stylesheet from `src/main.ts` in place of a separate
-`@c15t/svelte/styles.css` import:
+Import this stylesheet from `src/main.ts`:
 
 ```css title="src/app.css"
 @import 'tailwindcss';
-@import '@c15t/svelte/styles.css';
 
 @custom-variant dark (&:where(.dark, .dark *));
 ```
@@ -226,7 +224,6 @@ Import this stylesheet from your root `+layout.svelte`:
 
 ```css title="src/app.css"
 @import 'tailwindcss';
-@import '@c15t/svelte/styles.css';
 
 @custom-variant dark (&:where(.dark, .dark *));
 ```
@@ -256,8 +253,12 @@ c15t's parts, pass the URL of your built stylesheet in
 
 ## Set up Tailwind CSS 3
 
-Tailwind 3 loads the same `styles.css` as Tailwind 4 and needs one PostCSS
-plugin. Every c15t package that ships a stylesheet exports it as
+Tailwind 3's preflight is unlayered, so it beats the layered rules c15t
+renders itself and strips the banner's padding and borders. On Tailwind 3,
+turn those rules off with `styles: false` and import c15t's `styles.css`
+through a PostCSS plugin. The Astro integration needs only the plugin: it
+detects Tailwind 3 and links `c15t/astro/styles.css` itself. Every c15t
+package that ships a stylesheet exports the plugin as
 `<package>/postcss-tailwind3`, so use the one from the package you installed:
 
 | You installed                                             | Plugin name                       |
@@ -269,21 +270,26 @@ plugin. Every c15t package that ships a stylesheet exports it as
 They are the same plugin. A config that already lists
 `@c15t/ui/postcss-tailwind3` keeps working.
 
-Make three changes:
+Make four changes:
 
-1. Add the plugin to your PostCSS plugins, before `tailwindcss`. Write the plugins as an object, as the examples below do.
+1. Set `styles: false` where you configure c15t: `options` on `ConsentRoot`
+   in Next.js and TanStack Start, `options` on `ConsentProvider` in React,
+   and `styles={false}` on `ConsentManagerProvider` in Svelte and SvelteKit.
+   Vue, Nuxt and Astro need no change.
+2. Add the plugin to your PostCSS plugins, before `tailwindcss`. Write the plugins as an object, as the examples below do.
    PostCSS runs them in the order of the keys. Next.js also accepts an array
    of plugin names, but Vite's PostCSS loader rejects that form.
-2. Where you import c15t's stylesheet yourself, put the import above the
-   `@tailwind` directives, whatever your build tool. Vite drops an `@import`
+3. Import c15t's stylesheet above the `@tailwind` directives, whatever your
+   build tool. Vue, Nuxt and Astro skip this step. Vite drops an `@import`
    that follows another rule, with the warning
    `@import must precede all other statements`, and the banner renders
    unstyled. Next.js 16 with Turbopack fails the build.
-3. Set `darkMode: 'class'` so Tailwind's `dark:` variant follows the same
+4. Set `darkMode: 'class'` so Tailwind's `dark:` variant follows the same
    `dark` class c15t reads.
 
-The plugin also processes the stylesheets c15t loads for you, such as Astro's
-injected one. Without it, Tailwind 3 stops
+The plugin also processes the stylesheets the Vue and Nuxt components import,
+and the one the Astro integration adds on a Tailwind 3 site. Without it,
+Tailwind 3 stops
 the build with "`@layer components` is used but no matching
 `@tailwind components` directive is present", or purges c15t's rules, because
 c15t's class names never appear in your source.
@@ -293,8 +299,9 @@ class. Add the important modifier to utilities you pass to c15t parts:
 `!bg-red-500`, `hover:!bg-red-500`. A bare `bg-red-500` has no effect. Theme
 tokens work the same on Tailwind 3 and 4.
 
-In React and Next.js apps, `c15t setup` makes the first two changes when it
-finds Tailwind 3. It replaces an existing
+In React and Next.js apps, `c15t setup` adds the plugin and the stylesheet
+import when it finds Tailwind 3, but does not set `styles: false`. Add that
+yourself. It replaces an existing
 `styles.tw3.css` import from an earlier setup with `styles.css`. When it
 cannot edit your PostCSS config, it prints the step to do by hand. See
 [setup](https://c15t.com/docs/cli/commands/setup#set-up-styles-and-tailwind-css).
@@ -327,7 +334,7 @@ export default {
 
 Import `c15t/next/styles.css` above the directives. Turbopack fails the
 build when the import sits below them. The same order works with
-webpack:
+webpack. Set `styles: false` in `ConsentRoot`'s `options` as well:
 
 ```css title="app/globals.css"
 /* Turbopack rejects an @import below other rules, so it goes first. */
@@ -358,7 +365,8 @@ export default {
 ```
 
 Import `c15t/tanstack-start/styles.css` above the directives, in the
-stylesheet your root route links:
+stylesheet your root route links, and set `styles: false` in
+`ConsentRoot`'s `options`:
 
 ```css title="src/styles.css"
 /* Vite ignores an @import below other rules, so it goes first. */
@@ -388,8 +396,9 @@ export default {
 } satisfies Config;
 ```
 
-Import `c15t/react/styles.css` above the directives, and import this
-stylesheet from your entry module:
+Import `c15t/react/styles.css` above the directives, import this
+stylesheet from your entry module, and set `styles: false` in the
+`ConsentProvider` options:
 
 ```css title="src/app.css"
 /* Vite ignores an @import below other rules, so it goes first. */
@@ -489,8 +498,12 @@ export default {
 } satisfies Config;
 ```
 
-The plugin processes the stylesheet the integration injects, so the CSS
-entry holds only the directives:
+When the integration finds Tailwind 3 in the project, it adds
+`c15t/astro/styles.css` to every page through Astro's CSS pipeline
+instead of inlining the banner's rules, so the plugin processes it. You
+do not set `styles: false` or import c15t's stylesheet, and the CSS
+entry holds only the directives. The first paint still waits for that
+stylesheet:
 
 ```css title="src/styles/global.css"
 @tailwind base;
@@ -521,8 +534,9 @@ export default {
 } satisfies Config;
 ```
 
-Import `@c15t/svelte/styles.css` above the directives, and import this
-stylesheet from `src/main.ts`:
+Import `@c15t/svelte/styles.css` above the directives, import this
+stylesheet from `src/main.ts`, and pass `styles={false}` to
+`ConsentManagerProvider`:
 
 ```css title="src/app.css"
 /* Vite ignores an @import below other rules, so it goes first. */
@@ -556,8 +570,9 @@ export default {
 } satisfies Config;
 ```
 
-Import `@c15t/svelte/styles.css` above the directives, and import this
-stylesheet from your root `+layout.svelte`:
+Import `@c15t/svelte/styles.css` above the directives, import this
+stylesheet from your root `+layout.svelte`, and pass `styles={false}` to
+`ConsentManagerProvider`:
 
 ```css title="src/app.css"
 /* Vite ignores an @import below other rules, so it goes first. */

package/docs/customization/tokens.md

@@ -8,14 +8,14 @@ group: customization
 ## Where tokens come from
 
 c15t's components take their colors from `--c15t-*` CSS variables, and most
-of their fonts, radii, spacing, shadows and motion too. c15t's stylesheet sets
-the defaults. You change them with a theme object or with CSS, and every part
+of their fonts, radii, spacing, shadows and motion too. c15t's rules set the
+defaults. You change them with a theme object or with CSS, and every part
 that reads a token changes with it. Some values are still fixed for one
 component, such as button padding, the radius of the "Secured by" tag and
 several font sizes and weights, so a token change does not move them. Restyle
 those parts through [slots](./slots.md) or your own CSS.
 [Stylesheets and CSS layers](./stylesheets.md)
-covers which stylesheet to load, and [dark mode](./dark-mode.md)
+covers how c15t loads its rules, and [dark mode](./dark-mode.md)
 covers the dark set of tokens.
 
 ## Set semantic values together
@@ -59,9 +59,9 @@ setup.
 ## Combine a generated theme with your own CSS
 
 `generateThemeCSS` writes its variables on `:root:root` and
-`.c15t-theme-root.c15t-theme-root`, one step more specific than the defaults
-in `styles.css`. The theme therefore overrides the defaults whether its
-`<style>` element comes before or after the stylesheet. The same output backs
+`.c15t-theme-root.c15t-theme-root`, more specific than c15t's defaults. The
+theme therefore overrides the defaults whether its
+`<style>` element comes before or after c15t's rules. The same output backs
 `ConsentTheme` in React, Next.js and TanStack Start, Astro's `theme` option and
 the script tag's `ui.theme`.