@c15t/react 3.0.0-alpha.1 → 3.0.0-alpha.11

package/docs/customization/slots.md

@@ -1,55 +1,237 @@
 ---
-title: Style component slots
-description: Target a specific c15t component part without replacing its markup or behavior.
+title: Component parts
+description: 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.
 group: customization
 ---
 
-## Use slots for local changes
+## Which part API your framework uses
 
-In React and Next.js, put per-part attributes in `options.components`. This
-fragment belongs in an existing provider's options:
+Each framework has one way to add classes, inline styles or attributes to a
+single part of a stock component. The keys differ between the two
+vocabularies, so a configuration from one does not work in the other.
+
+| Framework               | Part API                                                                 | Keys look like            | Class key                |
+| ----------------------- | ------------------------------------------------------------------------ | ------------------------- | ------------------------ |
+| Next.js, TanStack Start | `options.components` in Next.js `c15t.config.ts`, or on `ConsentRoot`    | `components.banner.card`  | `className`              |
+| React                   | `components` in the `ConsentProvider` options                            | `components.banner.card`  | `className`              |
+| Nuxt                    | `components` in the `c15t` options, or in `app/app.config.ts`            | `components.banner.card`  | `class`                  |
+| Vue                     | `components` in the `c15tVue` options                                    | `components.banner.card`  | `class`                  |
+| Astro                   | `theme.slots` in the `c15t()` integration options                        | `slots.consentBannerCard` | A string, or `className` |
+| Svelte, SvelteKit       | `theme.slots` on `ConsentProvider` (Svelte) or `ConsentRoot` (SvelteKit) | `slots.consentBannerCard` | A string, or `className` |
+| HTML, JavaScript        | `ui.theme.slots`                                                         | `slots.consentBannerCard` | A string, or `className` |
+
+React and Vue also read `theme.slots` from the theme in their options, and
+apply each slot to the matching `components` part, such as
+`consentDialogCard` to `dialog.card` and `toggle` to `switch.root`. Where both
+set the same part, classes from both apply, inline styles merge with
+`components` winning per property, and any other attribute in `components`
+replaces the theme's. In Vue and Nuxt, each part object is bound with
+`v-bind`, so write `class` and `style` rather than React's `className`.
+
+Svelte's stock components, and Astro's `ConsentBanner`, `IABConsentBanner`
+and `ConsentDialogTrigger`, also take a `class` prop. On `ConsentBanner` it
+goes on the banner root.
+
+This React fragment belongs in the provider options:
 
 ```tsx
 components: {
   banner: {
-    card: { className: 'rounded-none shadow-none' },
-    title: { className: 'font-semibold' },
-    footer: { className: 'border-t' },
+    card: { className: 'brand-card' },
+    title: { style: { fontWeight: 600 } },
   },
+},
+```
+
+The same parts with `theme.slots`, which every framework reads:
+
+```ts
+theme: {
+  slots: {
+    consentBannerCard: 'brand-card',
+    consentBannerTitle: 'brand-title',
+  },
+},
+```
+
+A slot can also be `{ className, style }`. Svelte applies both on every part,
+including the IAB banner and dialog.
+
+[Class names and CSS-in-JS](./class-names.md) covers CSS
+Modules, vanilla-extract, StyleX and Emotion, and
+[Tailwind CSS](./tailwind.md) covers utilities on parts.
+
+## Banner parts
+
+| Part                                        | `components` key                     | `theme.slots` key                  | `data-testid`         |
+| ------------------------------------------- | ------------------------------------ | ---------------------------------- | --------------------- |
+| Positioning root, with the state attributes | `banner.root`                        | `consentBanner`                    | `consent-banner-root` |
+| Card sizing and branding container          | `banner.cardShell`                   | None                               |                       |
+| Visible card                                | `banner.card`                        | `consentBannerCard`                | `consent-banner-card` |
+| Title and description container             | `banner.header`                      | `consentBannerHeader`              |                       |
+| Title                                       | `banner.title`                       | `consentBannerTitle`               |                       |
+| Description                                 | `description.banner`                 | `consentBannerDescription`         |                       |
+| Action area                                 | `banner.footer`                      | `consentBannerFooter`              |                       |
+| Group of action groups                      | `banner.actions`                     | None                               |                       |
+| One group of equally prominent actions      | `banner.actionGroup`                 | `consentBannerFooterSubGroup`      |                       |
+| Group of right links                        | `banner.rights`                      | `consentBannerRights`              |                       |
+| One right link                              | `banner.rightLink`                   | `consentBannerRightLink`           |                       |
+| Backdrop of a blocking banner               | `banner.overlay`                     | `consentBannerOverlay`             |                       |
+| "Secured by" tag                            | `tag.banner`                         | `consentBannerTag`                 |                       |
+| Filled and outlined buttons                 | `button.primary`, `button.secondary` | `buttonPrimary`, `buttonSecondary` |                       |
+
+The button parts apply to every c15t button of that style, in the banner and
+the dialog. The script tag's banner has no rights group, so
+`consentBannerRights` does not apply there.
+
+## Preference dialog parts
+
+| Part             | `components` key     | `theme.slots` key          | `data-testid`         |
+| ---------------- | -------------------- | -------------------------- | --------------------- |
+| Positioner       | `dialog.root`        | None                       |                       |
+| Dialog container | `dialog.container`   | `consentDialog`            | `consent-dialog-root` |
+| Card             | `dialog.card`        | `consentDialogCard`        |                       |
+| Header           | `dialog.header`      | `consentDialogHeader`      |                       |
+| Title            | `dialog.title`       | `consentDialogTitle`       |                       |
+| Description      | `description.dialog` | `consentDialogDescription` |                       |
+| Content          | `dialog.content`     | `consentDialogContent`     |                       |
+| Backdrop         | `dialog.overlay`     | `consentDialogOverlay`     |                       |
+| "Secured by" tag | `tag.dialog`         | `consentDialogTag`         |                       |
+
+The stock dialog's footer is the preference widget's footer. Style it with
+`consentWidgetFooter`. There is no `consentDialogFooter` slot.
+
+## Preference widget parts
+
+The widget is the list of categories inside the dialog. React and Vue call it
+`manager`.
+
+| Part                   | `components` key                                                                                                                                                                                     | `theme.slots` key             |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| Widget root            | `manager.root`                                                                                                                                                                                       | `consentWidget`               |
+| Footer                 | `manager.footer`                                                                                                                                                                                     | `consentWidgetFooter`         |
+| Group of action groups | `manager.actions`                                                                                                                                                                                    | None                          |
+| One action group       | `manager.actionGroup`                                                                                                                                                                                | `consentWidgetFooterSubGroup` |
+| Category accordion     | `accordion.root`, `accordion.triggerRow`, `accordion.arrow`, `accordion.header`, `accordion.title`, `accordion.control`, `accordion.contentViewport`, `accordion.contentInner`                       | `consentWidgetAccordion`      |
+| One accordion item     | `accordion-item.root`, `accordion-item.trigger`, `accordion-item.content`                                                                                                                            | None                          |
+| Category switch        | `switch.root`, `switch.track`, `switch.thumb`                                                                                                                                                        | `toggle`                      |
+| Vendor list            | `vendor-list.root`, `vendor-list.trigger`, `vendor-list.content`, `vendor-list.item`, `vendor-list.header`, `vendor-list.name`, `vendor-list.description`, `vendor-list.link`, `vendor-list.control` | None                          |
+| "Secured by" tag       | `tag.manager` in React, `tag.dialog` in Vue                                                                                                                                                          | `consentWidgetTag`            |
+
+## Floating trigger parts
+
+| Part                         | `components` key                                                | `theme.slots` key                                                                                   |
+| ---------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Button                       | `trigger.root`                                                  | `consentDialogTrigger`                                                                              |
+| Icon                         | `trigger.icon`                                                  | `consentDialogTriggerIcon`                                                                          |
+| Label                        | `trigger.text`                                                  | None                                                                                                |
+| Toolbar, its items and icons | `trigger.toolbar`, `trigger.toolbarItem`, `trigger.toolbarIcon` | `consentDialogTriggerToolbar`, `consentDialogTriggerToolbarItem`, `consentDialogTriggerToolbarIcon` |
+
+React renders the toolbar from `ConsentDialogTriggerToolbar`, and while
+`ConsentDevTools` is mounted. Vue renders it only while `ConsentDevTools` is
+mounted. In Astro, the toolbar slots reach the React dialog.
+
+## Legal links and IAB TCF parts
+
+| Component                          | `components` keys                                                                                                                                                                                                                                                          | `theme.slots` keys                                                                                                                               |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Legal links                        | `legal-links.root`, and `link.banner`, `link.dialog`, `link.manager` for one link                                                                                                                                                                                          | None                                                                                                                                             |
+| IAB banner                         | `iab-banner.root`, `cardShell`, `card`, `header`, `title`, `description`, `partnersLink`, `purposeList`, `purposeMore`, `legitimateInterestNotice`, `footer`, `actions`, `actionGroup`, `overlay`                                                                          | `iabConsentBanner`, `iabConsentBannerCard`, `iabConsentBannerHeader`, `iabConsentBannerFooter`, `iabConsentBannerTag`, `iabConsentBannerOverlay` |
+| IAB dialog                         | `iab-dialog.root`, `card`, `header`, `headerContent`, `title`, `description`, `closeButton`, `body`, `content`, `loading`, `footer`, `tabs`, `tabsList`, `tabTrigger`, `tabIndicator`, `tabPanel`, `specialPurposes`, `consentNotice`, `actions`, `actionGroup`, `overlay` | `iabConsentDialog`, `iabConsentDialogCard`, `iabConsentDialogHeader`, `iabConsentDialogFooter`, `iabConsentDialogTag`, `iabConsentDialogOverlay` |
+| IAB purpose, stack and vendor rows | `iab-purpose-item.*`, `iab-stack-item.*`, `iab-vendor-list.*`                                                                                                                                                                                                              | None                                                                                                                                             |
+
+Legal links take no `theme.slots` key. They keep their stock link class, and
+a description slot's classes stay on the description around them.
+
+## ConsentGate placeholder parts
+
+`ConsentGate` shows a placeholder card while its category is denied. React,
+Next.js, TanStack Start, Vue, Nuxt, Svelte and SvelteKit render the same
+three parts:
+
+| Part                          | `components` key      | `theme.slots` key   | `data-testid`              |
+| ----------------------------- | --------------------- | ------------------- | -------------------------- |
+| Placeholder card              | `consent-gate.root`   | `consentGate`       | `consent-gate-placeholder` |
+| Title                         | `consent-gate.title`  | `consentGateTitle`  | `consent-gate-title`       |
+| Button that opens preferences | `consent-gate.button` | `consentGateButton` | `consent-gate-button`      |
+
+The button part applies on top of `button.primary`, or `buttonPrimary`. The
+parts only reach the built-in placeholder. A placeholder you pass yourself
+takes your own classes, and the wrapper around the gate takes `className` in
+React or `class` in Svelte. Astro, HTML and JavaScript have no `ConsentGate`.
+
+## Style parts from outside the script tag's shadow root
+
+The script tag and `init()` render into a shadow root. Every part that has a
+`theme.slots` key carries it in a `part` attribute, so page CSS can reach it
+with `::part()`:
+
+```css
+[data-c15t-ui]::part(consentBannerCard) {
+  border: 3px solid #6943a3;
 }
 ```
 
-The class names above assume Tailwind. A slot can also receive `style` and other
-supported element attributes. Keep shared colors and radius scales in tokens;
-use slots when only one component part should change.
+## Select on state attributes
+
+Parts carry `data-*` attributes that describe their state. Select on these
+instead of guessing at markup:
+
+| Element                  | Attributes                                                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| Banner root              | `data-prompt`, `data-model`, `data-variant`, `data-position`, `data-blocking`                                             |
+| Action buttons           | `data-action` (`accept`, `reject`, `customize`, `dismiss` or `save`), `data-variant`, `data-mode`                         |
+| Footer and action groups | `data-direction`, `data-fill`, `data-split`                                                                               |
+| Right links              | `data-action="right"`, `data-right`                                                                                       |
+| Preference dialog        | `data-state` (`open` or `closed`), on the elements listed in [motion](./motion.md#animate-your-own-rules-on-dialog-state) |
+| Category switch          | `data-state`, `data-disabled`                                                                                             |
+
+The script tag's banner root has `data-variant`, `data-position` and
+`data-blocking` only, with `data-blocking` set to `"true"` or `"false"`. Its
+right links carry `data-action="customize"`.
+
+The banner card does not inherit the root's attributes. With Tailwind, give
+the root `group` and read the root's attribute from a child part:
+
+```tsx
+components: {
+  banner: {
+    root: { className: 'group' },
+    card: { className: 'group-data-[variant=bar]:rounded-none' },
+  },
+},
+```
 
-## Read attributes on the right element
+Test notices as well as choice prompts. A notice has an acknowledge action,
+`data-action="dismiss"`, instead of accept and reject.
 
-The banner root carries `data-prompt`, `data-model`, `data-variant`,
-`data-position` and `data-blocking`. Its child card does not inherit those HTML
-attributes. In Tailwind, give the root `className: 'group'` and use
-`group-data-[variant=bar]:...` on a child slot.
+## Do not target c15t's class names
 
-| React banner slot                  | Use                                   |
-| ---------------------------------- | ------------------------------------- |
-| `root`                             | Position wrapper and state attributes |
-| `cardShell`                        | Card sizing and branding container    |
-| `card`                             | Visible card                          |
-| `header`, `title`, `description`   | Heading and explanatory copy          |
-| `footer`, `actions`, `actionGroup` | Action layout                         |
-| `rights`, `rightLink`              | Preferences access controls           |
-| `overlay`                          | Backdrop for blocking presentation    |
+c15t's stock class names are generated from CSS Modules and end in a hash, such
+as `c15t-ui-card-lgjVq`. The hash changes whenever the source CSS changes, and
+the classes disappear under `noStyle`. A rule that targets one breaks on an
+upgrade without warning. Target a part API, `data-testid`, a `data-*`
+attribute or `::part()` instead.
 
-Buttons expose `data-action` for action-specific CSS. Test notices as well as
-choice prompts; a notice uses acknowledgement rather than accept/reject.
+## Remove c15t's classes with noStyle
 
-## When to remove styles
+`noStyle` renders the same markup and behavior without c15t's stock classes. It
+keeps your part classes and styles, `data-testid` and the `data-*` attributes.
+It does not replace layout, spacing, focus indicators or responsive behavior,
+so use it when you intend to write all of that yourself.
 
-`noStyle` removes the built-in component styling. It does not supply replacement
-layout, spacing, focus indicators or responsive behavior. Use it when you intend
-to own all of that work, not as the first response to a token that appears to do
-nothing.
+| Framework                      | Where                                                                                                                                                                                              |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Next.js, TanStack Start, React | `noStyle` in the provider options for every component, or the `noStyle` prop on `ConsentBanner`, `ConsentDialog`, `ConsentWidget`, `ConsentDialogTrigger` and the IAB components                   |
+| Svelte, SvelteKit              | `noStyle` in the provider options, or the prop on a stock component                                                                                                                                |
+| Astro                          | `noStyle` prop on `ConsentBanner` and `IABConsentBanner`                                                                                                                                           |
+| HTML, JavaScript               | `ui.noStyle`, which also drops the bundled stylesheet                                                                                                                                              |
+| Vue, Nuxt                      | The `noStyle` prop on `ConsentWidget`, and on the `PreferenceItemRoot` and `PreferenceItemContent` primitives, whose other parts follow the root. The banner, dialog and trigger have no `noStyle` |
 
-If the markup itself must change, use the adapter's compound components or
-headless API. The slot objects above are the React contract; check Vue and Svelte
-slot types before reusing them.
+In `theme.slots`, `{ noStyle: true }` on one slot replaces that part's stock
+classes in Svelte, Astro's banner and the script tag. React and Vue, including
+Astro's React and Vue dialog islands, ignore a slot's `noStyle`, so its classes
+apply on top of the stock ones. If the markup itself must change, use your framework's compound
+components or headless API.

package/docs/customization/stylesheets.md

@@ -0,0 +1,248 @@
+---
+title: Stylesheets and CSS layers
+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
+---
+
+## 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://v3.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` in `c15t.config.ts` or 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 `ConsentProvider` or `ConsentRoot`   | `@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)             |
+
+```ts title="c15t.config.ts (Next.js)"
+import { defineConsentConfig } from 'c15t/next';
+
+export default defineConsentConfig({ 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
+
+| 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                                                                                                                                                                                                                                                                                                                                                |
+
+`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`
+module and `c15t/astro/dialog.css` are now empty and stay only so existing
+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, and each `<style>`
+element the surfaces render, opens with Tailwind CSS 4's layer order:
+
+```css
+@layer properties, theme, base, components, utilities;
+```
+
+Cascade layers rank by the order they are first named, so `components` stays
+above Tailwind's preflight in `base` and below `utilities`, whichever
+stylesheet loads first. Without Tailwind the other layers stay empty. Vue's
+per-component stylesheets open with the same statement.
+
+What this means for your overrides:
+
+* Any unlayered rule of yours outranks every c15t component rule, whatever its
+  specificity or load order. You do not need `!important`.
+* A rule in one of your own layers wins only if that layer comes after
+  `components` in the layer order.
+* Tokens are not layered. Set them as described in
+  [theme tokens](./tokens.md).
+
+If your CSS declares its own layer order, load that statement before c15t's
+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
+
+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';
+/* Only with ui: 'svelte'. */
+@import 'c15t/astro/primitives.css';
+/* Only when the integration sets iab. */
+@import 'c15t/astro/iab/styles.css';
+```
+
+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
+
+The script tag and `init()` from `@c15t/browser` render into a shadow root with
+their own copy of the stylesheet. Your page's CSS does not reach the UI, and
+the UI's CSS does not reach your page. To style it:
+
+| Option                                       | What it does                                                                                                                                                               |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ui.theme`                                   | Tokens, written after the stylesheet inside the shadow root                                                                                                                |
+| `ui.css`                                     | A string of CSS added after the stylesheet and the theme                                                                                                                   |
+| `ui.stylesheetURLs`                          | Stylesheets linked inside the shadow root, after c15t's, with the client's `nonce`. They load asynchronously, so the first frame can render without them                   |
+| `::part()`                                   | Page CSS that reaches a part by its slot key, as in `[data-c15t-ui]::part(consentBannerCard)`                                                                              |
+| `ui.shadow: false`, or `data-shadow="false"` | Renders into the page, so your stylesheets apply. c15t still injects its stylesheet next to the UI                                                                         |
+| `ui.styles: false`                           | Drops the injected stylesheet. With `shadow: false`, load `@c15t/browser/styles.css` from your bundle, or link `dist/c15t.css` from the same package version as the script |
+
+A stylesheet in `ui.stylesheetURLs` should also load on the page. Some CSS,
+such as Tailwind 4's `@property` rules, only takes effect in the page's
+stylesheets. Of these options, the script tag has an attribute for `shadow`
+only. Set the others with `c15t.push(['config', { ui: { ... } }])`.
+
+## Run without c15t's styles
+
+`noStyle` removes c15t's stock classes from the markup, and in the script tag
+also the injected stylesheet. Your part classes, `data-testid` and the `data-*`
+attributes stay. [Component parts](./slots.md#remove-c15ts-classes-with-nostyle)
+lists where each framework takes it.
+
+`noStyle` does not supply layout, spacing, focus indicators or responsive
+behavior. If a token seems to do nothing, check the layer order and your
+selector before you reach for `noStyle`.
+
+## Check the result
+
+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.