@c15t/react 3.0.0-alpha.3 → 3.0.0-alpha.5

package/docs/concepts/how-consent-works.md

@@ -0,0 +1,123 @@
+---
+title: How consent works
+description: What c15t decides on each page load, the difference between a
+  permission and a recorded choice, and what happens when a visitor saves.
+group: concepts
+---
+
+## What c15t decides on each page load
+
+On every page load c15t answers one question for each consent category: is
+this allowed right now? To answer it, c15t:
+
+1. Selects a **policy** for the visitor, usually by country and region. The
+   policy says whether optional categories start denied (opt-in) or allowed
+   (opt-out), and whether to show a banner.
+2. Reads the visitor's **stored choice** from a cookie and localStorage, if
+   there is one that still matches the policy.
+3. Reads **privacy signals** such as Global Privacy Control (GPC).
+
+The result is a set of **permissions**, one per category. Components, script
+loaders, embeds and your own code read those permissions. Nothing optional
+runs until the policy has resolved: while it loads, and if it fails, every
+optional category is denied.
+
+A banner is only the interface. It does not stop a script you load with a
+plain `<script>` tag or a vendor SDK you initialize yourself. To gate that code,
+register it with c15t. See [integrations](../integrations/overview.md).
+
+## Categories
+
+| Category        | Use it for                                         |
+| --------------- | -------------------------------------------------- |
+| `necessary`     | Code the site cannot work without. Always allowed. |
+| `functionality` | Optional features such as support chat.            |
+| `measurement`   | Analytics and usage measurement.                   |
+| `experience`    | Personalization.                                   |
+| `marketing`     | Advertising, retargeting and pixels.               |
+
+Assign a category by what the code does, not by what would be convenient.
+Calling analytics `necessary` does not make it necessary.
+[Consent categories](./consent-categories.md) explains which
+categories the preference dialog shows and how policy scope affects them.
+
+## Policies
+
+A policy has a **model** and a **prompt**:
+
+| Model     | Optional categories before a choice                               |
+| --------- | ----------------------------------------------------------------- |
+| `opt-in`  | Denied until the visitor allows them.                             |
+| `opt-out` | Allowed until the visitor refuses them or sends a privacy signal. |
+| `iab`     | Controlled by an IAB TCF consent string.                          |
+| `none`    | Allowed, with no prompt.                                          |
+
+| Prompt   | What the visitor sees                                                          |
+| -------- | ------------------------------------------------------------------------------ |
+| `choice` | A banner asking for a decision.                                                |
+| `notice` | A notice they can dismiss. Dismissing records an acknowledgement, not consent. |
+| `none`   | Nothing on load. The policy can still require a way to open preferences.       |
+
+With [Inth](https://inth.com) you manage policies in your project, and the app
+receives them from the backend. Changing a stylesheet or importing a preset in
+the browser does not override a hosted policy.
+[Policies](./policies.md) covers presets, scope, and why a banner may
+not appear.
+
+## A permission is not a recorded choice
+
+These two values answer different questions, and mixing them up is the most
+common integration bug:
+
+* **Permission** (`effectivePermissions`, `useConsent('measurement')`) answers
+  "may this run now?" Under an opt-out policy it can be `true` before the
+  visitor has done anything.
+* **Recorded choice** (`explicitChoice`) answers "what did the visitor decide?"
+  It only changes when the visitor accepts, rejects or saves preferences.
+
+| Task                                                 | Read                |
+| ---------------------------------------------------- | ------------------- |
+| Load a script or render an optional feature          | Permission          |
+| Show what the visitor chose, or report consent rates | Recorded choice     |
+| Decide whether a prompt is needed                    | `promptRequirement` |
+| Find out why a region behaves differently            | `policyRule`        |
+| Check that the policy loaded                         | `resolution.status` |
+
+Never turn a permission into a saved choice. Hydrating server state, reading a
+cookie or rendering a component does not count as a visitor action.
+`onChoiceRecorded` fires only for a visitor's action; `onPermissionsChanged`
+also fires when a choice expires or a privacy signal changes.
+
+## Notices and privacy signals
+
+Dismissing a notice acknowledges it. It grants nothing and leaves earlier
+refusals in place.
+
+GPC is a browser setting that asks sites not to sell or share data. c15t reads
+it live on every evaluation and applies the restrictions your policy configures
+for it. It never becomes a stored refusal: when the browser stops sending GPC,
+the restriction ends. The backend also sees the current value.
+
+## What happens when a visitor saves
+
+When a visitor clicks Accept, Reject or Save, c15t:
+
+1. Updates permissions and closes the banner or dialog in the same click.
+   Scripts, embeds and network rules follow the new permissions immediately.
+2. Writes the choice to the cookie and localStorage.
+3. Sends the choice to the consent backend. If the request fails, the choice
+   stays saved in the browser and the request is retried later.
+4. Reloads the page if the visitor turned off something they had allowed.
+   Code that already ran cannot be unloaded, so the reload starts a page with
+   only permitted code. Set `reloadOnConsentRevoked: false` to handle revocation
+   yourself.
+
+The [consent state reference](./consent-state.md) documents the exact
+ordering, retries, server hydration and how open tabs stay in step.
+
+## Where consent data comes from
+
+A consent backend supplies policies and stores consent records. Use Inth, run
+the [c15t backend](https://c15t.com/docs/self-host/overview) yourself, or keep policies in the
+browser for local development. [Choose your setup](./choose-your-setup.md)
+walks through the options for your framework and hosting.

package/docs/{frameworks/react/concepts/policy-presets.md → concepts/policies.md}

@@ -1,8 +1,8 @@
 ---
-title: Policy presets
-description: Understand how policy rules affect React prompts, permissions and
-  persistent privacy controls.
-group: frameworks
+title: Policies
+description: How policy models, prompts and scope decide what c15t asks
+  visitors, where to change the rules, and why a banner may not appear.
+group: concepts
 ---
 
 ## What the policy controls
@@ -29,12 +29,12 @@ must do the same.
 Use `effectivePermissions` to gate a script or embed. A `true` value under an
 opt-out rule does not mean the visitor clicked Accept. Read `explicitChoice`
 when you need the visitor's recorded decision. See
-[consent state](../../../guides/consent-state.md) for these distinctions.
+[how consent works](./how-consent-works.md#a-permission-is-not-a-recorded-choice) for these distinctions.
 
 ## Where to change the rules
 
 For Inth, configure policy rules on your hosted project. The app receives those
-rules through the configured [data-fetching path](../../../guides/data-fetching.md). Importing
+rules through the configured [data-fetching path](./data-fetching.md). Importing
 `recommendedPolicyRules()` or changing browser styling does not override the
 hosted policy.
 
@@ -42,7 +42,7 @@ For a backend you operate, use the
 [policy packs guide](https://c15t.com/docs/self-host/guides/policy-packs). It covers
 `manifest.policyRules`, preset selection and custom matchers. Browser-only
 setups own their rules locally; see
-[deployment modes](../../../guides/deployment-modes.md).
+[choose your setup](./choose-your-setup.md).
 
 Presets are starting configurations. Select them for your actual processing,
 and review their assumptions before allowing optional categories by default.
@@ -69,55 +69,3 @@ default for other known locations. An unknown country uses its strict opt-in
 fallback. A US country with a missing state gets the US opt-out fallback.
 These are the local pack's defaults, not a promise about your Inth project.
 Browser-only mode does not discover a visitor's country from their IP address.
-
-## Inspect the active policy
-
-Place this diagnostic component inside your existing consent
-provider. It reads state without recording a choice.
-
-```tsx title="src/consent-policy-debug.tsx"
-import { useSnapshot } from 'c15t/react';
-
-export function ConsentPolicyDebug() {
-  const snapshot = useSnapshot();
-  const resolution = snapshot.resolution;
-
-  return (
-    <pre>
-      {JSON.stringify(
-        {
-          status: resolution.status,
-          policy: resolution.status === 'matched' ? resolution.policy.id : null,
-          prompt: snapshot.promptRequirement,
-          permissions: snapshot.effectivePermissions,
-          location: snapshot.location,
-          privacySignals: snapshot.privacySignals,
-        },
-        null,
-        2,
-      )}
-    </pre>
-  );
-}
-```
-
-The diagnostic subscribes to consent changes. Remove it after verification.
-For a production feature gate, use `useConsent('marketing')` or the category
-your feature needs instead of subscribing to the whole snapshot.
-
-## Change appearance without changing policy
-
-Keep one banner and one dialog in your existing
-provider. Use
-[styling](../styling/overview.md) to change their appearance,
-or [headless UI](../headless.md) for custom markup.
-Presentation settings change layout and emphasis; policy rules decide which
-actions and privacy rights the app must expose.
-
-## Verify policy behavior
-
-Use a fresh browser profile to check the intended location, then repeat with a
-saved rejection and GPC enabled. Confirm that the expected prompt and
-preferences controls appear, and that denied scripts and embeds make no
-requests. Test missing location inputs too. Follow
-[verify consent](../../../guides/verify-consent.md) for the full flow.

package/docs/customization/class-names.md

@@ -0,0 +1,202 @@
+---
+title: Class names and CSS-in-JS
+description: Style c15t's component parts with CSS Modules, vanilla-extract,
+  StyleX, Emotion or plain class names, and see which approach works in each
+  framework.
+group: customization
+---
+
+## Pass a class to a part
+
+CSS Modules, vanilla-extract, StyleX, Emotion and Tailwind all end up as a class
+on an element and a rule in a stylesheet. Give c15t the class through your
+framework's part API, and the rule wins over c15t's own rule for that part:
+c15t's rules sit in the `components` cascade layer, and an unlayered rule from
+your stylesheet outranks any layered one.
+
+Each example below adds a 3px colored border and 4px corners to the banner card.
+The React examples run as Storybook stories in CI, which check that each class
+lands on the card and that the computed border comes from the class, not from
+c15t's own card rule. The script tag examples run in the example app's browser
+tests.
+
+| Framework                      | Part API                                                                | Class key                                 | Inline `style` | Where the class's CSS must load                                                      |
+| ------------------------------ | ----------------------------------------------------------------------- | ----------------------------------------- | -------------- | ------------------------------------------------------------------------------------ |
+| Next.js, TanStack Start, React | `components.<component>.<part>`, or `theme.slots`                       | `className`                               | Yes            | Anywhere on the page                                                                 |
+| Nuxt, Vue                      | `components.<component>.<part>`, or `theme.slots`                       | `class` (`className` in `theme.slots`)    | Yes            | Anywhere on the page                                                                 |
+| Svelte, SvelteKit              | `theme.slots`, or `class` on a component                                | A string, or `className` in a slot object | Yes            | A global stylesheet, or `:global()`                                                  |
+| Astro                          | `theme.slots` in the integration options, or `class` on `ConsentBanner` | A string, or `className` in a slot object | Yes            | A global stylesheet                                                                  |
+| HTML, JavaScript               | `ui.theme.slots`                                                        | A string, or `className` in a slot object | Yes            | Inside the shadow root through `ui.stylesheetURLs`, or anywhere with `shadow: false` |
+
+[Component parts](./slots.md) lists the parts and their keys in
+each framework.
+
+## CSS Modules
+
+Import the module and pass its class. This works wherever your bundler compiles
+CSS Modules:
+
+```css title="src/banner.module.css"
+.card {
+	border: 3px solid rgb(219 39 119);
+	border-radius: 4px;
+}
+```
+
+```ts title="src/consent-components.ts"
+import type { ConsentProviderOptions } from 'c15t/react';
+
+import styles from './banner.module.css';
+
+/** Pass as `components` in your ConsentProvider options. */
+export const components: ConsentProviderOptions['components'] = {
+	banner: { card: { className: styles.card } },
+};
+```
+
+Pass `components` in your `ConsentProvider` options, or in `options` on
+`ConsentRoot` in Next.js and TanStack Start.
+
+## vanilla-extract
+
+vanilla-extract compiles `style()` calls in `.css.ts` files to static CSS at
+build time. Add its plugin for your bundler, such as
+`@vanilla-extract/vite-plugin`, then pass the class:
+
+```ts title="src/consent-components.css.ts"
+import { style } from '@vanilla-extract/css';
+import type { ConsentProviderOptions } from 'c15t/react';
+
+const card = style({ border: '3px solid rgb(37 99 235)', borderRadius: 4 });
+
+/** Pass as `components` in your ConsentProvider options. */
+export const components: ConsentProviderOptions['components'] = {
+	banner: { card: { className: card } },
+};
+```
+
+## StyleX
+
+`stylex.props()` returns `className` and, for dynamic values, `style`. A React
+part accepts both, so spread the result into the part. Add the StyleX compiler
+plugin for your bundler, such as `@stylexjs/unplugin`:
+
+```ts title="src/consent-components.ts"
+import * as stylex from '@stylexjs/stylex';
+import type { ConsentProviderOptions } from 'c15t/react';
+
+const styles = stylex.create({
+	card: {
+		borderColor: 'rgb(22 163 74)',
+		borderRadius: 4,
+		borderStyle: 'solid',
+		borderWidth: 3,
+	},
+});
+
+/**
+ * Pass as `components` in your ConsentProvider options. `stylex.props()`
+ * returns `className` and, for dynamic styles, `style`; the slot takes both.
+ */
+export const components: ConsentProviderOptions['components'] = {
+	banner: { card: stylex.props(styles.card) },
+};
+```
+
+StyleX writes atomic classes into an unlayered stylesheet, so they outrank
+c15t's layered rules without extra specificity.
+
+## Emotion
+
+`css()` from `@emotion/css` returns a class name and inserts its rule into a
+`<style>` element in the document `<head>` when your code runs:
+
+```ts title="src/consent-components.ts"
+import { css } from '@emotion/css';
+import type { ConsentProviderOptions } from 'c15t/react';
+
+const card = css({ border: '3px solid rgb(234 88 12)', borderRadius: 4 });
+
+/** Pass as `components` in your ConsentProvider options. */
+export const components: ConsentProviderOptions['components'] = {
+	banner: { card: { className: card } },
+};
+```
+
+Emotion inserts its rules into the page, not into a shadow root. With the HTML
+script tag or `@c15t/browser`, set `ui: { shadow: false }` so the UI renders
+in the page where those rules reach it. `ui.stylesheetURLs` cannot carry them,
+because they have no URL.
+
+## Use other frameworks' part APIs
+
+Vue and Nuxt bind a part's object to the element with `v-bind`, so write
+`class` rather than `className`. A class string from CSS Modules,
+vanilla-extract or Emotion works the same way. To use StyleX, map its
+`className` to `class`.
+
+Svelte scopes component styles, so a class defined in a component's `<style>`
+block does not reach a c15t part. Define it in a global stylesheet or with
+`:global(.your-class)`. `theme.slots` accepts a string or
+`{ className, style }`, and `class` on `ConsentBanner` goes on the banner root.
+
+Astro serializes its integration options, so `theme.slots` in
+`astro.config.mjs` takes plain strings and objects. Use class names from a
+global stylesheet or Tailwind there. Build-time tools that export class names
+from a module, such as CSS Modules, cannot reach `astro.config.mjs`.
+
+## Style the script tag's shadow root
+
+The script tag and `init()` from `@c15t/browser` render into a shadow root. A
+class from your page's stylesheet reaches a part only if the stylesheet reaches
+the shadow root. Pick one:
+
+* **`ui.stylesheetURLs`.** c15t links each URL inside the shadow root, after
+  its own stylesheet. Link the stylesheet that holds your classes, such as your
+  CSS Modules or Tailwind build.
+* **`::part()`.** Every part with a slot key carries it in a `part` attribute.
+  Page CSS can style it with `[data-c15t-ui]::part(consentBannerCard)`,
+  without any class.
+* **`ui.css`.** A string of CSS that c15t adds inside the shadow root.
+* **`shadow: false`.** c15t renders into the page and every page stylesheet
+  applies, including Emotion's.
+
+This example links a Tailwind build into the shadow root and puts utilities on
+two parts:
+
+```html title="index.html"
+<link
+	rel="stylesheet"
+	href="/tailwind.css"
+/>
+<script>
+	window.c15t = window.c15t || [];
+	c15t.push([
+		'config',
+		{
+			ui: {
+				// The banner renders in a shadow root, where the page's
+				// stylesheets do not reach. Link your Tailwind build into it
+				// too, and keep the page's own link: Tailwind 4 registers
+				// variables with @property, which only works in the page.
+				stylesheetURLs: ['/tailwind.css'],
+				theme: {
+					slots: {
+						consentBannerCard: 'rounded-none border-4 border-sky-600',
+						consentBannerTitle: 'uppercase tracking-wide',
+					},
+				},
+			},
+		},
+	]);
+</script>
+```
+
+## Check the result
+
+1. Open the page in a private window so the banner shows.
+2. Select the banner card in the Elements panel. It carries your class.
+3. In the Styles panel, your rule applies and c15t's rule for the same
+   property is struck out. If your class is on the element but its rule is
+   missing, the stylesheet does not reach the part. Check the "Where the class's CSS
+   must load" column in [Pass a class to a part](#pass-a-class-to-a-part).

package/docs/customization/dark-mode.md

@@ -0,0 +1,157 @@
+---
+title: Dark mode
+description: Switch c15t's banner and dialog to dark colors with colorScheme,
+  set your own dark tokens, follow your site's theme switch, and paint dark on
+  the first frame in every framework.
+group: customization
+---
+
+## How c15t turns dark
+
+c15t's stylesheet switches every `--c15t-*` color token to its dark value when
+`<html>` has a `dark` or a `c15t-dark` class. The `colorScheme` option decides
+whether c15t sets `c15t-dark` itself:
+
+| `colorScheme` | What c15t does with `c15t-dark`                                          |
+| ------------- | ------------------------------------------------------------------------ |
+| `'light'`     | Removes it once                                                          |
+| `'dark'`      | Adds it once                                                             |
+| `'system'`    | Follows `prefers-color-scheme`, including changes while the page is open |
+| Unset         | Copies your `dark` class into `c15t-dark` and follows it as it changes   |
+| `null`        | Leaves it alone. Your site sets it                                       |
+
+Astro also accepts `'none'`, which means the same as `null`.
+
+`'light'` only removes `c15t-dark`. If your site puts `dark` on `<html>`, the
+stylesheet still switches the tokens to dark. Pick one class convention for
+your site and let c15t follow it.
+
+## Defaults in each framework
+
+| Framework               | Where to set it                                                                   | Default              |
+| ----------------------- | --------------------------------------------------------------------------------- | -------------------- |
+| Next.js, TanStack Start | `options.colorScheme` on `ConsentRoot`, and `colorScheme` on `ConsentTheme`       | Unset: copies `dark` |
+| React                   | `colorScheme` in the `ConsentProvider` options, and on `ConsentTheme`             | Unset: copies `dark` |
+| Nuxt                    | `colorScheme` under the `c15t` key in `nuxt.config.ts`, or in `app/app.config.ts` | Unset: copies `dark` |
+| Vue                     | `colorScheme` in the `c15tVue` options                                            | Unset: copies `dark` |
+| Astro                   | `colorScheme` in the `c15t()` integration options                                 | `'system'`           |
+| Svelte, SvelteKit       | `colorScheme` on `ConsentManagerProvider`                                         | Unset: copies `dark` |
+| HTML                    | `data-color-scheme` on the script tag: `light`, `dark`, `system` or `none`        | `system`             |
+| JavaScript              | `ui.colorScheme` in `init()`                                                      | `'system'`           |
+
+React, Vue and Svelte apps usually already have a theme switch that toggles a
+`dark` class, such as next-themes. Copying that class keeps c15t in step with
+the site without extra code.
+
+Astro and the script tag default to `'system'` because neither can rely on a
+site convention. Astro paints the banner from server HTML before any site
+script runs, and Astro sites share no `dark` class convention, so following the
+operating system is the one choice its inline script can make correctly. A plain
+HTML page has no convention either. A site that has one opts in with `null`.
+
+### Set colorScheme null in Nuxt
+
+In Nuxt, set `colorScheme: null` under the `c15t` key in `nuxt.config.ts` or
+in `app/app.config.ts`. Nuxt drops a `null` in inline module options, such as
+`modules: [['@c15t/vue', { colorScheme: null }]]`, before the module reads it,
+so c15t would copy your `dark` class as if `colorScheme` were unset.
+
+## Follow your site's theme switch
+
+In React, Next.js, TanStack Start, Vue, Nuxt, Svelte and SvelteKit, leave
+`colorScheme` unset and toggle `dark` on `<html>`. c15t watches the class and switches with
+it. Include the class in the server HTML when your site renders dark, so the
+first paint matches.
+
+In Astro, set `colorScheme: 'none'` and toggle `c15t-dark` together with your
+own class. A `ClientRouter` navigation replaces the attributes of `<html>`, so
+set the class again on `astro:after-swap` if your theme script does not.
+
+With the script tag, add `data-color-scheme="none"`. With `init()`, pass
+`ui: { colorScheme: null }`. The UI is then dark while `<html>` has `dark` or
+`c15t-dark`, and follows the class as it changes. The UI renders in a shadow
+root that the page's class cannot reach, so c15t copies the class onto the
+shadow host.
+
+If your site sets `c15t-dark` itself in React, Next.js, TanStack Start, Vue,
+Nuxt, Svelte or SvelteKit, pass `colorScheme: null` so c15t leaves it alone.
+
+## Set your own dark colors
+
+Theme tokens take a `dark` object with the same color keys as `colors`. Every
+color you set in `colors` also applies in dark mode, unless `dark` sets it too,
+so give a dark value for each brand color:
+
+```ts title="consent-theme.ts"
+export const theme = {
+	colors: { primary: '#2f6f4e', primaryHover: '#24563c', surface: '#fbf8f3' },
+	dark: { primary: '#7fd1a8', primaryHover: '#9fdcbd', surface: '#1b1f1d' },
+};
+```
+
+Where the theme goes depends on the framework:
+
+* **React, Next.js, TanStack Start.** Pass it to `ConsentTheme`. To write the
+  CSS outside a component, call `generateThemeCSS(theme, colorScheme)` from
+  `c15t/react/utils`, or `@c15t/react/utils` if you installed the scoped
+  package. It writes the same CSS as `ConsentTheme`.
+* **Vue, Nuxt.** Pass it as `theme` in the plugin or module options. It goes
+  into the `<style id="c15t-css-vars">` element with `tokens`.
+* **Astro.** Pass it as `theme` in the integration options.
+* **SvelteKit, Svelte.** Pass it to `generateThemeCSS(theme, colorScheme)` from
+  `@c15t/ui/theme` on the server.
+* **HTML, JavaScript.** Pass it as `ui.theme`.
+
+This Nuxt example follows the system setting and uses its own dark primary
+color. Every other dark token keeps c15t's default:
+
+```ts title="nuxt.config.ts (c15t options)"
+// Follow the visitor's system setting, with a dark primary of our own.
+colorScheme: 'system',
+theme: { dark: { primary: '#7fd1a8' } },
+```
+
+To set dark values in plain CSS instead, write them for both classes:
+
+```css
+:root.dark,
+:root.c15t-dark {
+  --c15t-primary: #7fd1a8;
+  --c15t-surface: #1b1f1d;
+}
+```
+
+A generated theme, such as the output of `ConsentTheme` or
+`generateThemeCSS`, writes its dark values on `:root:root.dark` and
+`:root:root.c15t-dark`. Those selectors outrank the rule above. If you use both,
+put dark values in the theme, or repeat `:root` in your own selectors.
+
+## Paint dark on the first frame
+
+A banner that renders light and then turns dark flashes. How to avoid that
+depends on where the banner first renders:
+
+| Framework               | What to do                                                                                                                                                                                                                                                                                                                                      |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Next.js, TanStack Start | Render `<ConsentTheme theme={theme} colorScheme="system" />` on the server, with the same value as `options.colorScheme`. `'dark'` writes dark tokens as the default and `'system'` adds a `prefers-color-scheme` media query, so the server HTML is dark before hydration. With `colorScheme` unset, put your `dark` class in the server HTML. |
+| React                   | Render `<ConsentTheme colorScheme="system" />` next to the provider, with the same value as the provider's `colorScheme`. Its CSS makes the tokens dark from the first frame, before the provider sets the class. In a server-rendered React app, render it on the server.                                                                      |
+| Nuxt                    | For `'dark'` and `'system'`, the module adds an inline script to `<head>` that sets `c15t-dark` before the server-rendered banner paints. It carries the module's `nonce`. With `colorScheme` unset, put your `dark` class in the server HTML.                                                                                                  |
+| Vue                     | The plugin applies `colorScheme` and writes the tokens when you install it, before the first render.                                                                                                                                                                                                                                            |
+| Astro                   | `ConsentScript` in `<head>` sets the class from an inline script before the banner paints, and c15t sets it again after each `ClientRouter` navigation. Keep `ConsentScript` in your layout's `<head>`.                                                                                                                                         |
+| Svelte                  | The provider sets the class as it mounts. With `colorScheme` unset, the stylesheet reads your `dark` class directly, so the tokens are dark from the first frame.                                                                                                                                                                               |
+| SvelteKit               | Pass the scheme to `generateThemeCSS(theme, 'system')` in your server load, so the CSS in `<svelte:head>` already has the media query. With `colorScheme` unset, put your `dark` class in the server HTML.                                                                                                                                      |
+| HTML, JavaScript        | c15t applies the scheme when it mounts the UI, before any surface renders.                                                                                                                                                                                                                                                                      |
+
+[Theme tokens](./tokens.md) lists every color token, and your
+framework's customize page shows where its theme goes.
+
+## Check the result
+
+1. Open the page in a private window with your operating system in dark mode,
+   or add your `dark` class to `<html>`.
+2. The banner is dark on its first frame. Reload with the Network panel
+   throttled to see the first paint.
+3. Open the preference dialog. It uses the same dark tokens as the banner.
+4. Switch the scheme while the page is open. With `'system'` or an unset
+   `colorScheme`, the banner and dialog follow without a reload.
+5. Check the contrast of the primary button text in both schemes.