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

package/docs/customization/tailwind.md

@@ -0,0 +1,863 @@
+---
+title: Tailwind CSS
+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
+---
+
+## How c15t's styles meet Tailwind
+
+c15t's component rules live in the CSS cascade layer `components`. Each c15t
+stylesheet starts with Tailwind CSS 4's layer order,
+`@layer properties, theme, base, components, utilities;`, and cascade layers
+rank by the order they are first named. On Tailwind 4, c15t's rules stay above
+Tailwind's preflight in `base` and below your utilities in `utilities`,
+whichever stylesheet loads first. A plain utility such as `p-2` on a c15t part
+wins without `!important`.
+
+Tailwind CSS 3 has no cascade layers. It treats `@layer components` as its own
+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`. 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
+fixture. The Next.js 15 and webpack fixtures use the same files. The check
+confirms that c15t's banner and dialog keep their styles under Tailwind's
+preflight, that a padding utility on the banner root
+beats c15t's own padding, and that the `dark:` variant applies. The fixtures run
+without a backend, so they use `offline()` mode or a local `backendURL`. Keep the
+`mode` or `backendURL` from your quickstart.
+
+## Set up Tailwind CSS 4
+
+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**
+
+Next.js runs Tailwind 4 through `@tailwindcss/postcss`:
+
+```js title="postcss.config.mjs"
+export default { plugins: { '@tailwindcss/postcss': {} } };
+```
+
+Import Tailwind in the global stylesheet that `app/layout.tsx` or
+`pages/_app.tsx` loads:
+
+```css title="app/globals.css"
+@import 'tailwindcss';
+
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+**TanStack Start**
+
+Add `@tailwindcss/vite` before the TanStack Start plugin:
+
+```ts title="vite.config.ts"
+import tailwindcss from '@tailwindcss/vite';
+import { tanstackStart } from '@tanstack/react-start/plugin/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	plugins: [
+		tailwindcss(),
+		tanstackStart({ prerender: { enabled: true } }),
+		react(),
+	],
+});
+```
+
+Import Tailwind from the stylesheet your root route links:
+
+```css title="src/styles.css"
+@import 'tailwindcss';
+
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+**React**
+
+```ts title="vite.config.ts"
+import tailwindcss from '@tailwindcss/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [react(), tailwindcss()] });
+```
+
+Import this stylesheet from your entry module:
+
+```css title="src/app.css"
+@import 'tailwindcss';
+
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+**Nuxt**
+
+Add `@tailwindcss/vite` under `vite.plugins` and list your CSS entry in
+`css`. The Vue components load c15t's styles themselves:
+
+```ts title="nuxt.config.ts"
+import tailwindcss from '@tailwindcss/vite';
+import { hosted } from 'c15t/vue';
+
+export default defineNuxtConfig({
+	c15t: { backendURL: '/api/c15t', mode: hosted() },
+	compatibilityDate: '2026-07-04',
+	css: ['~/assets/css/main.css'],
+	modules: ['c15t/vue'],
+	ssr: false,
+	vite: { plugins: [tailwindcss()] },
+});
+```
+
+Your CSS entry imports Tailwind and declares the dark variant:
+
+```css title="app/assets/css/main.css"
+@import 'tailwindcss';
+
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+**Vue**
+
+The Vue components load their own stylesheets, so the CSS entry holds only
+Tailwind:
+
+```ts title="vite.config.ts"
+import tailwindcss from '@tailwindcss/vite';
+import vue from '@vitejs/plugin-vue';
+import { consentManifest } from 'c15t/vue/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	plugins: [vue(), consentManifest({ backendURL: '/api/c15t' }), tailwindcss()],
+});
+```
+
+Import this stylesheet from `src/main.ts`:
+
+```css title="src/style.css"
+@import 'tailwindcss';
+
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+**Astro**
+
+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';
+import tailwindcss from '@tailwindcss/vite';
+import { defineConfig } from 'astro/config';
+import c15t, { offline } from 'c15t/astro';
+
+export default defineConfig({
+	integrations: [
+		svelte(),
+		c15t({
+			mode: offline({
+				policyRules: [
+					{
+						id: 'tailwind-matrix',
+						match: { isDefault: true },
+						model: 'opt-in',
+						prompt: 'choice',
+					},
+				],
+			}),
+		}),
+	],
+	vite: { plugins: [tailwindcss()] },
+});
+```
+
+Import this stylesheet from your layout:
+
+```css title="src/styles/global.css"
+@import 'tailwindcss';
+
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+**Svelte**
+
+```ts title="vite.config.ts"
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+import tailwindcss from '@tailwindcss/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [svelte(), tailwindcss()] });
+```
+
+Import this stylesheet from `src/main.ts`:
+
+```css title="src/app.css"
+@import 'tailwindcss';
+
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+**SvelteKit**
+
+```ts title="vite.config.ts"
+import { sveltekit } from '@sveltejs/kit/vite';
+import tailwindcss from '@tailwindcss/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [tailwindcss(), sveltekit()] });
+```
+
+Import this stylesheet from your root `+layout.svelte`:
+
+```css title="src/app.css"
+@import 'tailwindcss';
+
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+**HTML**
+
+The script tag renders its UI in a shadow root with its own copy of c15t's
+stylesheet. Build your Tailwind CSS as usual and link it from the page:
+
+```css title="style.css"
+@import 'tailwindcss';
+
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+To put utilities on c15t's parts, link the same build into the shadow root
+with `ui.stylesheetURLs`, as in
+[put utilities on c15t parts](#put-utilities-on-c15t-parts).
+
+**JavaScript**
+
+`init()` from `@c15t/browser` renders into a shadow root, the same way as
+the script tag. Build Tailwind as usual for your page. To put utilities on
+c15t's parts, pass the URL of your built stylesheet in
+`ui.stylesheetURLs`, as in
+[put utilities on c15t parts](#put-utilities-on-c15t-parts).
+
+## Set up Tailwind CSS 3
+
+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                       |
+| --------------------------------------------------------- | --------------------------------- |
+| `c15t` (React, Next.js, TanStack Start, Vue, Nuxt, Astro) | `c15t/postcss-tailwind3`          |
+| `@c15t/svelte` (Svelte, SvelteKit)                        | `@c15t/svelte/postcss-tailwind3`  |
+| `@c15t/browser` (script tag in the light DOM)             | `@c15t/browser/postcss-tailwind3` |
+
+They are the same plugin. A config that already lists
+`@c15t/ui/postcss-tailwind3` keeps working.
+
+Make four changes:
+
+1. Set `styles: false` where you configure c15t: `options` in Next.js
+   `c15t.config.ts`, `options` on `ConsentRoot` in TanStack Start, `options`
+   on `ConsentProvider` in React, and `styles={false}` on `ConsentProvider` in
+   Svelte or `ConsentRoot` in 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.
+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.
+4. Set `darkMode: 'class'` so Tailwind's `dark:` variant follows the same
+   `dark` class c15t reads.
+
+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.
+
+Tailwind 3 has no cascade layers, so c15t's selectors outrank a single utility
+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` 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://v3.c15t.com/docs/cli/commands/setup#set-up-styles-and-tailwind-css).
+
+Create React App ignores PostCSS config files, so Tailwind 3 cannot run the
+plugin and the build fails on c15t's stylesheet. `c15t setup` warns
+about this. Add the plugin before `tailwindcss` through CRACO, eject, or move
+the app to Vite.
+
+**Next.js**
+
+Next.js loads `postcss.config.mjs` itself:
+
+```js title="postcss.config.mjs"
+export default {
+	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
+};
+```
+
+Scan `app/` and turn on the class-based dark variant:
+
+```ts title="tailwind.config.ts"
+import type { Config } from 'tailwindcss';
+
+export default {
+	content: ['./app/**/*.{ts,tsx}'],
+	darkMode: 'class',
+} satisfies Config;
+```
+
+Import `c15t/next/styles.css` above the directives. Turbopack fails the
+build when the import sits below them. The same order works with
+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. */
+@import 'c15t/next/styles.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+**TanStack Start**
+
+```js title="postcss.config.mjs"
+export default {
+	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
+};
+```
+
+Scan your source and turn on the class-based dark variant:
+
+```ts title="tailwind.config.ts"
+import type { Config } from 'tailwindcss';
+
+export default {
+	content: ['./src/**/*.{ts,tsx}'],
+	darkMode: 'class',
+} satisfies Config;
+```
+
+Import `c15t/tanstack-start/styles.css` above the directives, in the
+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. */
+@import 'c15t/tanstack-start/styles.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+**React**
+
+```js title="postcss.config.mjs"
+export default {
+	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
+};
+```
+
+Scan your source and turn on the class-based dark variant:
+
+```ts title="tailwind.config.ts"
+import type { Config } from 'tailwindcss';
+
+export default {
+	content: ['./index.html', './src/**/*.{ts,tsx}'],
+	darkMode: 'class',
+} satisfies Config;
+```
+
+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. */
+@import 'c15t/react/styles.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+**Nuxt**
+
+Nuxt reads PostCSS plugins from `postcss.plugins` in `nuxt.config.ts`, in
+the order listed:
+
+```ts title="nuxt.config.ts"
+import { hosted } from 'c15t/vue';
+
+export default defineNuxtConfig({
+	c15t: { backendURL: '/api/c15t', mode: hosted() },
+	compatibilityDate: '2026-07-04',
+	css: ['~/assets/css/main.css'],
+	modules: ['c15t/vue'],
+	postcss: {
+		plugins: {
+			'c15t/postcss-tailwind3': {},
+			tailwindcss: {},
+			autoprefixer: {},
+		},
+	},
+	ssr: false,
+});
+```
+
+Scan `app/` and turn on the class-based dark variant:
+
+```ts title="tailwind.config.ts"
+import type { Config } from 'tailwindcss';
+
+export default {
+	content: ['./app/**/*.{vue,ts}'],
+	darkMode: 'class',
+} satisfies Config;
+```
+
+The Vue components load c15t's styles themselves, and the plugin processes
+them too, so the CSS entry holds only the directives:
+
+```css title="app/assets/css/main.css"
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+**Vue**
+
+```js title="postcss.config.mjs"
+export default {
+	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
+};
+```
+
+Scan your source and turn on the class-based dark variant:
+
+```ts title="tailwind.config.ts"
+import type { Config } from 'tailwindcss';
+
+export default {
+	content: ['./index.html', './src/**/*.{vue,ts}'],
+	darkMode: 'class',
+} satisfies Config;
+```
+
+The Vue components load their own stylesheets, and the plugin processes
+them too, so the CSS entry holds only the directives:
+
+```css title="src/style.css"
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+**Astro**
+
+```js title="postcss.config.mjs"
+export default {
+	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
+};
+```
+
+Scan your source and turn on the class-based dark variant:
+
+```ts title="tailwind.config.ts"
+import type { Config } from 'tailwindcss';
+
+export default {
+	content: ['./src/**/*.{astro,html,ts}'],
+	darkMode: 'class',
+} satisfies Config;
+```
+
+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;
+@tailwind components;
+@tailwind utilities;
+```
+
+**Svelte**
+
+```js title="postcss.config.mjs"
+export default {
+	plugins: {
+		'@c15t/svelte/postcss-tailwind3': {},
+		tailwindcss: {},
+		autoprefixer: {},
+	},
+};
+```
+
+Scan your source and turn on the class-based dark variant:
+
+```ts title="tailwind.config.ts"
+import type { Config } from 'tailwindcss';
+
+export default {
+	content: ['./index.html', './src/**/*.{svelte,ts}'],
+	darkMode: 'class',
+} satisfies Config;
+```
+
+Import `@c15t/svelte/styles.css` above the directives, import this
+stylesheet from `src/main.ts`, and pass `styles={false}` to
+`ConsentProvider`:
+
+```css title="src/app.css"
+/* Vite ignores an @import below other rules, so it goes first. */
+@import '@c15t/svelte/styles.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+**SvelteKit**
+
+```js title="postcss.config.mjs"
+export default {
+	plugins: {
+		'@c15t/svelte/postcss-tailwind3': {},
+		tailwindcss: {},
+		autoprefixer: {},
+	},
+};
+```
+
+Scan your source and turn on the class-based dark variant:
+
+```ts title="tailwind.config.ts"
+import type { Config } from 'tailwindcss';
+
+export default {
+	content: ['./src/**/*.{html,svelte,ts}'],
+	darkMode: 'class',
+} satisfies Config;
+```
+
+Import `@c15t/svelte/styles.css` above the directives, import this
+stylesheet from your root `+layout.svelte`, and pass `styles={false}` to
+`ConsentRoot`:
+
+```css title="src/app.css"
+/* Vite ignores an @import below other rules, so it goes first. */
+@import '@c15t/svelte/styles.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+**HTML**
+
+In the default shadow root, c15t's stylesheet never meets Tailwind, so the
+page's Tailwind 3 setup needs nothing from c15t:
+
+```css title="style.css"
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+To render the UI in the page instead, see
+[render the UI in the light DOM](#render-the-ui-in-the-light-dom).
+
+**JavaScript**
+
+`init()` renders into a shadow root by default, where c15t's stylesheet
+never meets Tailwind. To render the UI in the page and build c15t's rules
+into your Tailwind CSS, see
+[render the UI in the light DOM](#render-the-ui-in-the-light-dom).
+
+## Put utilities on c15t parts
+
+Pass utilities to a component part through your framework's part API. The
+fixtures put padding on the banner root, which c15t also pads, with a different
+value in dark mode. On Tailwind 4 a plain utility wins. On Tailwind 3, add `!`,
+as in `!p-[7px] dark:!p-[11px]`, because c15t's unlayered rules outrank a plain
+utility. [Component parts](./slots.md) lists the parts each
+framework exposes.
+
+Tailwind only generates classes it finds in the files its `content` globs or
+`@source` rules scan. Keep part classes in a scanned file.
+
+**Next.js**
+
+Add the classes to `options.components` on `ConsentRoot`, in the
+`'use client'` wrapper from your quickstart:
+
+```tsx title="app/consent.tsx"
+options={{
+	components: {
+		banner: {
+			root: { className: 'p-[7px] dark:p-[11px]' },
+		},
+	},
+	mode,
+}}
+```
+
+**TanStack Start**
+
+```tsx title="src/routes/__root.tsx"
+options={{
+	components: {
+		banner: {
+			root: { className: 'p-[7px] dark:p-[11px]' },
+		},
+	},
+	mode,
+}}
+```
+
+**React**
+
+```tsx title="src/main.tsx"
+const options = {
+	components: { banner: { root: { className: 'p-[7px] dark:p-[11px]' } } },
+	mode,
+};
+```
+
+**Nuxt**
+
+Tailwind scans `app/`, not `nuxt.config.ts`, so put part classes in
+`app/app.config.ts` under the `c15t` key. The module merges it with the
+`c15t` options in `nuxt.config.ts`. Vue takes `class`, not `className`:
+
+```ts title="app/app.config.ts"
+// Tailwind scans `app/`, so keep slot classes here rather than in
+// nuxt.config.ts.
+export default defineAppConfig({
+	c15t: {
+		components: { banner: { root: { class: 'p-[7px] dark:p-[11px]' } } },
+	},
+});
+```
+
+**Vue**
+
+Add the classes to `components` in the `c15tVue` options. Vue takes
+`class`, not `className`:
+
+```ts title="src/main.ts"
+.use(c15tVue, {
+	components: {
+		banner: {
+			root: { class: 'p-[7px] dark:p-[11px]' },
+		},
+	},
+	mode: hosted(),
+})
+```
+
+**Astro**
+
+`class` on `ConsentBanner` goes on the banner root:
+
+```astro title="src/pages/index.astro"
+<ConsentBanner class="p-[7px] dark:p-[11px]" />
+```
+
+**Svelte**
+
+`class` on `ConsentBanner` goes on the banner root:
+
+```svelte title="src/App.svelte"
+<ConsentBanner class="p-[7px] dark:p-[11px]" />
+```
+
+**SvelteKit**
+
+```svelte title="src/routes/+layout.svelte"
+<ConsentBanner class="p-[7px] dark:p-[11px]" />
+```
+
+**HTML**
+
+Put the classes on parts with `ui.theme.slots`, and link your Tailwind
+build into the shadow root with `ui.stylesheetURLs`. Keep the page's own
+link too. Tailwind 4 registers some of its variables with `@property`,
+which only takes effect in the page's stylesheets, not a shadow root's:
+
+```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>
+```
+
+Tailwind must scan the file that holds the slot classes.
+
+**JavaScript**
+
+Pass `ui.stylesheetURLs` and `ui.theme.slots` to `init()`. Keep a link to
+the same stylesheet on the page, because Tailwind 4's `@property` rules
+only take effect there:
+
+```ts title="src/consent.ts (partial)"
+ui: {
+  stylesheetURLs: ['/tailwind.css'],
+  theme: {
+    slots: {
+      consentBannerCard: 'rounded-none border-4 border-sky-600',
+    },
+  },
+},
+```
+
+## Use the dark variant
+
+The fixtures make Tailwind's `dark:` variant follow a `dark` class on `<html>`:
+`@custom-variant dark (&:where(.dark, .dark *));` on Tailwind 4 and
+`darkMode: 'class'` on Tailwind 3. c15t's stylesheet reads the same class, and
+in React, Next.js, TanStack Start, Vue, Nuxt, Svelte and SvelteKit an unset
+`colorScheme` also copies it into `c15t-dark`. One toggle then switches your
+utilities and c15t's dark tokens together.
+
+Astro and the script tag follow the system setting by default. [Dark mode](./dark-mode.md) covers each
+case.
+
+## Render the UI in the light DOM
+
+The script tag and `init()` render into a shadow root, so your page's CSS does
+not reach c15t and c15t's CSS does not reach your page. To style the UI with
+your page's Tailwind build directly, render it in the page with
+`data-shadow="false"` or `ui: { shadow: false }`.
+
+On Tailwind 4, that is the whole change. c15t still injects its layered
+stylesheet, and the layer order keeps it above preflight:
+
+```html title="light-dom.html"
+<script
+	src="/c15t.offline.js"
+	data-mode="offline"
+	data-country="DE"
+	data-shadow="false"
+	defer
+></script>
+```
+
+On Tailwind 3, keep the default shadow root. Tailwind 3's preflight is
+unlayered, so in the page it beats c15t's layered rules whatever their
+specificity and removes the button padding and card borders. Linking
+`c15t.css` from the page does not help, because nothing removes its layers.
+
+To render in the light DOM anyway, turn the injected sheet off with
+`styles: false`, and build c15t's rules into your Tailwind CSS with the plugin
+instead:
+
+```html title="light-dom.html"
+<script>
+	window.c15t = [['config', { ui: { shadow: false, styles: false } }]];
+</script>
+<script
+	src="/c15t.offline.js"
+	data-mode="offline"
+	data-country="DE"
+	defer
+></script>
+```
+
+Import `@c15t/browser/styles.css` above the directives in your Tailwind entry.
+Install `@c15t/browser@alpha`, which provides both the stylesheet and
+`@c15t/browser/postcss-tailwind3`:
+
+```css title="style.css"
+/*
+ * With `shadow: false`, c15t's injected stylesheet is layered and Tailwind
+ * 3's preflight is not, so preflight wins. Turn the injected sheet off and
+ * build c15t's rules into your Tailwind CSS instead.
+ */
+@import '@c15t/browser/styles.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+```js title="postcss.config.mjs"
+export default {
+	plugins: {
+		'@c15t/browser/postcss-tailwind3': {},
+		tailwindcss: {},
+		autoprefixer: {},
+	},
+};
+```
+
+In the light DOM your page's global rules reach the banner too, so check
+buttons and headings after the switch.
+
+## Check the result
+
+1. Build the app and open it in a private window. The banner has its card
+   background, border and button padding, so preflight did not reset it.
+2. Inspect the part you gave a utility. In the Styles panel, your utility is
+   applied and c15t's rule for the same property is struck out.
+3. Add the `dark` class to `<html>`. Your `dark:` utility applies and, where
+   c15t follows the class, the banner switches to dark colors.
+4. Open the preference dialog. Its rules come from a separate stylesheet in
+   most frameworks, so check that it is styled too.