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

package/docs/customization/recipes.md

@@ -1,79 +1,870 @@
 ---
-title: Banner styling recipes
-description: See real v3 components and reuse the exact theme configuration
-  behind the examples.
+title: Banner designs
+description: Five consent banner designs built with c15t, from one prop to your
+  own markup, with tested code for React, Vue, Svelte, Astro and plain HTML.
 group: customization
 ---
 
-## A branded floating card
+## Pick a design
 
-This theme uses a green primary action and a four-pixel large radius. Accept and
-Reject keep matching treatment. The component's required action behavior stays
-intact.
+Each design below is a real c15t banner. The screenshots and the code come from
+the same Storybook stories, which CI runs to check that each design renders and
+that Accept and Reject record a choice.
 
-![A v3 floating consent card with green Customize action, matching Accept and Reject buttons, and compact corners](../assets/v3/brand-card.png)
+| Design                        | Customization level     | Frameworks                |
+| ----------------------------- | ----------------------- | ------------------------- |
+| [Bottom bar](#bottom-bar)     | Props                   | React, Vue, Astro, Svelte |
+| [Branded card](#branded-card) | Theme tokens            | React                     |
+| [Choice wall](#choice-wall)   | Props                   | React                     |
+| [Slim bar](#slim-bar)         | Compound parts or slots | React, Vue, Svelte        |
+| [Headless bar](#headless-bar) | Headless                | React, Vue, Svelte, HTML  |
 
-```ts
-import { defineTheme } from '@c15t/ui/theme';
+Next.js and TanStack Start apps use the React code, with the same components
+imported from `c15t/next` or `c15t/tanstack-start`. Nuxt uses the Vue code and
+SvelteKit uses the Svelte code. [Customization](./overview.md)
+explains when to use each level.
+
+Every design keeps the policy in charge. The policy decides which buttons a
+visitor gets, and none of these designs records consent until the visitor
+clicks a button.
+
+## Bottom bar
+
+![A white bar across the bottom of a coffee shop page, with the heading "We value your privacy", one line of copy, and Reject All, Accept All and Customize buttons on the right](../assets/v3/bottom-bar.png)
+
+The stock banner becomes a full-width bar along the bottom edge with one prop,
+`variant="bar"`. The title and copy sit on the left and the buttons on the
+right.
+
+**React**
+
+Render `CookieBanner` in place of `ConsentBanner`, inside your
+`ConsentProvider` and next to `ConsentDialog`.
+
+```tsx title="src/cookie-banner.tsx"
+import { ConsentBanner } from 'c15t/react';
+
+/** The stock banner, drawn as a full-width bar along the bottom edge. */
+export const CookieBanner = () => (
+	<ConsentBanner variant="bar" position="bottom" />
+);
+```
+
+**Vue**
+
+Render `CookieBanner` and `ConsentManager` from
+`c15t/vue/runtime/components/consent-manager.vue` in place of
+`ConsentRoot`. To keep `ConsentRoot`, set `presentation.prompt` in the
+`c15tVue` options instead, as in [customize](https://v3.c15t.com/docs/frameworks/vue/customize).
+
+```vue title="src/CookieBanner.vue"
+<script setup lang="ts">
+import ConsentBanner from 'c15t/vue/runtime/components/consent-banner.vue';
+</script>
+
+<template>
+	<!-- The stock banner, drawn as a full-width bar along the bottom edge. -->
+	<ConsentBanner variant="bar" position="bottom" />
+</template>
+```
+
+**Astro**
+
+Add `presentation` to the `c15t()` options in `astro.config.mjs`. The
+server renders the banner as a bar.
+
+```ts title="astro.config.mjs (partial)"
+presentation: {
+	prompt: { position: 'bottom', variant: 'bar' },
+},
+```
+
+**Svelte**
+
+Render `CookieBanner` in place of `ConsentBanner`, inside
+`ConsentProvider` and next to `ConsentDialog`.
+
+```svelte title="src/lib/cookie-banner.svelte"
+<script lang="ts">
+	import { ConsentBanner } from '@c15t/svelte';
+</script>
+
+<!-- The stock banner, drawn as a full-width bar along the bottom edge. -->
+<ConsentBanner variant="bar" position="bottom" />
+```
+
+The HTML script tag takes the same shape through `presentation.prompt`. See
+[customize the script tag](https://v3.c15t.com/docs/frameworks/html/customize#change-the-banners-shape-and-position).
+
+## Branded card
+
+![A floating card in the bottom-left corner with a warm off-white surface, serif type, small corners, and green Reject All and Accept All buttons next to an outlined Customize button](../assets/v3/brand-card.png)
+
+Theme tokens change the colors, type and radius of the stock card without
+touching its markup. This theme sets a green primary color, an off-white
+surface, a serif font and four-pixel corners, and fills the actions the policy
+marks as primary. Here the policy marks both Reject All and Accept All as
+primary, so neither choice stands out.
+
+```ts title="src/consent-theme.ts"
+import { defineTheme } from 'c15t/react';
 
 export const brandTheme = defineTheme({
-	colors: { primary: '#2f6f4e' },
-	consentActions: {
-		primary: { mode: 'filled', variant: 'primary' },
+	colors: {
+		border: '#e4dccf',
+		primary: '#2f6f4e',
+		primaryHover: '#24563c',
+		surface: '#fbf8f3',
+		textOnPrimary: '#ffffff',
 	},
-	radius: { lg: '4px' },
+	consentActions: { primary: { mode: 'filled', variant: 'primary' } },
+	radius: { lg: '4px', md: '4px' },
+	typography: { fontFamily: 'Georgia, "Times New Roman", serif' },
 });
-
 ```
 
-Install `@c15t/ui` to use `defineTheme` directly. Pass `brandTheme` as `theme` in
-your existing React or Next.js provider options. Keep your Inth mode and script
-configuration. The theme source above is also imported by the runnable example,
-so the rendered result and the documentation use the same values.
+```tsx title="src/consent-ui.tsx"
+import { ConsentBanner, ConsentDialog, ConsentTheme } from 'c15t/react';
 
-## Change the shape without rebuilding the banner
+import { brandTheme } from './consent-theme';
+
+/**
+ * Render inside your ConsentProvider, and pass `theme: brandTheme` in the
+ * provider options so the action styles apply too.
+ */
+export const ConsentUI = () => (
+	<>
+		<ConsentTheme theme={brandTheme} />
+		<ConsentBanner />
+		<ConsentDialog />
+	</>
+);
+```
+
+`ConsentTheme` renders the tokens as a `<style>` element. In a server-rendered
+app, render it from a Server Component or the root layout so the tokens arrive
+with the HTML. The provider's `theme` option reads only `consentActions` and
+slot styles, so pass the same object there for the filled buttons:
 
 ```tsx
-<ConsentBanner variant="bar" />
+<ConsentProvider options={{ mode, theme: brandTheme }}>
 ```
 
-![The same green theme on a full-width v3 consent bar with the actions arranged across its footer](../assets/v3/brand-bar.png)
+The preferences dialog reads the same tokens:
 
-A bar changes the prompt's footprint. It does not change policy, grant categories
-or require a headless implementation.
+![The Privacy Settings dialog over the dimmed coffee shop page, with the same off-white surface, serif type and green Reject All and Accept All buttons](../assets/v3/brand-preferences.png)
 
-```tsx
-<ConsentBanner variant="wall" />
+Vue, Svelte, Astro and the script tag set the same tokens their own way. See
+customize for [Vue](https://v3.c15t.com/docs/frameworks/vue/customize),
+[Svelte](https://v3.c15t.com/docs/frameworks/svelte/customize),
+[Astro](https://v3.c15t.com/docs/frameworks/astro/customize) or
+[HTML](https://v3.c15t.com/docs/frameworks/html/customize), and
+[theme tokens](./tokens.md) for every token.
+
+## Choice wall
+
+![A centered consent card over a dimmed coffee shop page, with Reject All, Accept All and Customize buttons](../assets/v3/choice-wall.png)
+
+`variant="wall"` centers the stock banner over a backdrop, locks scrolling and
+traps focus until the visitor chooses. Use it only where a policy requires a
+choice before the page is usable.
+
+```tsx title="src/cookie-banner.tsx"
+import { ConsentBanner } from 'c15t/react';
+
+/** A centered prompt with a backdrop. The page waits for a choice. */
+export const CookieBanner = () => <ConsentBanner variant="wall" />;
+```
+
+A choice wall always blocks. A notice never blocks, so a wall requested for a
+notice falls back to the floating card.
+
+## Slim bar
+
+![A thin white bar along the bottom of the page with the heading and one line of copy on the left, and Reject All, Accept All and Customize buttons on the same row](../assets/v3/slim-bar.png)
+
+The slim bar puts the title, the copy and the buttons on one row, so it is
+shorter than the stock bar. React builds it from the
+`ConsentBanner` compound parts. Vue and Svelte have no compound banner parts,
+so they add classes to the stock bar's card and header through slots. All
+three use the same stylesheet, and all three keep the buttons the policy
+requires.
+
+**React**
+
+`ConsentBanner.PolicyActions` renders the policy's buttons, so a required
+Reject button stays. Render `CookieBanner` inside your `ConsentProvider`,
+next to `ConsentDialog`.
+
+```tsx title="src/cookie-banner.tsx"
+import { ConsentBanner } from 'c15t/react';
+
+import './slim-bar.css';
+
+/**
+ * The title, copy and the policy's buttons in a single row. The compound
+ * parts keep the policy's actions, so a required Reject button stays.
+ */
+export const CookieBanner = () => (
+	<ConsentBanner.Root variant="bar">
+		<ConsentBanner.Card className="slim-bar">
+			<ConsentBanner.Header className="slim-bar__text">
+				<ConsentBanner.Title />
+				<ConsentBanner.Description />
+			</ConsentBanner.Header>
+			<ConsentBanner.PolicyActions />
+		</ConsentBanner.Card>
+	</ConsentBanner.Root>
+);
+```
+
+**Vue**
+
+Spread `slimBar` into the options you pass to `app.use(c15tVue, ...)`.
+`ConsentRoot` then renders the slim bar.
+
+```ts title="src/consent-options.ts"
+import type { C15tVuePluginOptions } from 'c15t/vue/vue-plugin';
+
+import './slim-bar.css';
+
+/**
+ * Spread into the options you pass to `app.use(c15tVue, ...)`. The bar keeps
+ * the stock markup and actions; the slot classes put it on one row.
+ */
+export const slimBar = {
+	components: {
+		banner: {
+			card: { class: 'slim-bar' },
+			header: { class: 'slim-bar__text' },
+		},
+	},
+	presentation: { prompt: { position: 'bottom', variant: 'bar' } },
+} satisfies C15tVuePluginOptions;
+```
+
+**Svelte**
+
+Spread `slimBar` into the props you pass to `ConsentProvider`.
+Svelte scopes component styles, so the classes live in a global
+stylesheet.
+
+```ts title="src/lib/consent-options.ts"
+import type { ConsentManagerOptions } from '@c15t/svelte';
+
+import './slim-bar.css';
+
+/**
+ * Spread into the options you pass to `ConsentProvider`. The bar
+ * keeps the stock markup and actions; the slot classes put it on one row.
+ */
+export const slimBar = {
+	presentation: { prompt: { position: 'bottom', variant: 'bar' } },
+	theme: {
+		slots: {
+			consentBannerCard: 'slim-bar',
+			consentBannerHeader: 'slim-bar__text',
+		},
+	},
+} satisfies Partial<ConsentManagerOptions>;
+```
+
+```css title="src/slim-bar.css"
+.slim-bar {
+	box-sizing: border-box;
+	display: flex;
+	flex-wrap: wrap;
+	align-items: center;
+	gap: 0.5rem 1.5rem;
+	padding: 0.5rem 1.5rem;
+}
+
+/* Title and description share one line. */
+.slim-bar__text {
+	display: flex;
+	flex: 1 1 20rem;
+	flex-direction: row;
+	flex-wrap: wrap;
+	align-items: baseline;
+	gap: 0 0.5rem;
+	padding: 0;
+}
+
+/* The actions share the text's row, so drop the footer's own box. */
+.slim-bar > [data-testid='consent-banner-footer'] {
+	padding: 0;
+	border: 0;
+	background: none;
+}
+```
+
+## Headless bar
+
+![A dark navy bar across the bottom of the page with one line of white copy, an underlined Preferences link, and white pill-shaped Reject all and Accept all buttons](../assets/v3/headless-bar.png)
+
+The headless bar is your own markup and CSS, driven by c15t's headless API. It
+shows the same design in every framework. The policy still decides which
+buttons appear and in what order, the Preferences button is always there, and
+a choice is recorded only when the visitor clicks.
+
+**React**
+
+`useHeadlessConsentUI()` from `c15t/react/headless` returns the banner
+state and `performAction`. Render `CookieBar` in place of
+`ConsentBanner`, and keep `ConsentDialog`, which Preferences opens.
+
+```tsx title="src/cookie-bar.tsx"
+import { useHeadlessConsentUI } from 'c15t/react/headless';
+import type { HeadlessConsentBannerAction } from 'c15t/react/headless';
+
+import './cookie-bar.css';
+
+const labels: Record<HeadlessConsentBannerAction, string> = {
+	accept: 'Accept all',
+	customize: 'Preferences',
+	dismiss: 'Got it',
+	reject: 'Reject all',
+	save: 'Save',
+};
+
+export const CookieBar = () => {
+	const { banner, openDialog, performAction } = useHeadlessConsentUI();
+
+	if (!banner.isVisible) {
+		return null;
+	}
+
+	// The policy decides which actions this visitor gets, and in what order.
+	// Preferences has its own button, so it is always there.
+	const actions = banner.orderedActions.filter(
+		(action) => action !== 'customize'
+	);
+
+	return (
+		<section className="cookie-bar" aria-label="Cookie consent">
+			<p className="cookie-bar__text">
+				We use cookies to measure traffic and improve this site. Choose which
+				ones can run.
+			</p>
+			<div className="cookie-bar__actions">
+				<button type="button" className="cookie-bar__link" onClick={openDialog}>
+					Preferences
+				</button>
+				{actions.map((action) => (
+					<button
+						key={action}
+						type="button"
+						className="cookie-bar__button"
+						onClick={() => performAction(action)}
+					>
+						{labels[action]}
+					</button>
+				))}
+			</div>
+		</section>
+	);
+};
+```
+
+**Vue**
+
+The composables from `c15t/vue/vue-plugin` give the policy's actions and
+the active surface. Render `CookieBar` and `ConsentManager` in place of
+`ConsentRoot`. Preferences sets `activeUI` to `'manager'`, which opens
+`ConsentManager`.
+
+```vue title="src/CookieBar.vue"
+<script setup lang="ts">
+import {
+	useConsentActiveUI,
+	useConsentPolicyActions,
+	useConsentSave,
+	useDismissNotice,
+	usePromptRequirement,
+} from 'c15t/vue/vue-plugin';
+import { computed } from 'vue';
+
+import './cookie-bar.css';
+
+const labels: Record<string, string> = {
+	accept: 'Accept all',
+	dismiss: 'Got it',
+	reject: 'Reject all',
+};
+
+const activeUI = useConsentActiveUI();
+const prompt = usePromptRequirement();
+const { actionGroups } = useConsentPolicyActions('prompt');
+const saveConsent = useConsentSave();
+const dismissNotice = useDismissNotice();
+
+const isVisible = computed(
+	() => activeUI.value === 'banner' && prompt.value.kind !== 'none'
+);
+
+// The policy decides which actions this visitor gets, and in what order.
+// Preferences has its own button, so it is always there.
+const actions = computed(() =>
+	actionGroups.value.flat().filter((action) => action in labels)
+);
+
+const run = (action: string) => {
+	if (action === 'accept') {
+		void saveConsent('all');
+	} else if (action === 'reject') {
+		void saveConsent('none');
+	} else if (action === 'dismiss') {
+		void dismissNotice();
+	}
+};
+</script>
+
+<template>
+	<section v-if="isVisible" class="cookie-bar" aria-label="Cookie consent">
+		<p class="cookie-bar__text">
+			We use cookies to measure traffic and improve this site. Choose which ones
+			can run.
+		</p>
+		<div class="cookie-bar__actions">
+			<button
+				type="button"
+				class="cookie-bar__link"
+				@click="activeUI = 'manager'"
+			>
+				Preferences
+			</button>
+			<button
+				v-for="action in actions"
+				:key="action"
+				type="button"
+				class="cookie-bar__button"
+				@click="run(action)"
+			>
+				{{ labels[action] }}
+			</button>
+		</div>
+	</section>
+</template>
+```
+
+**Svelte**
+
+`getHeadlessConsent()` returns the banner state and `performAction`.
+Render `CookieBar` in place of `ConsentBanner`, inside
+`ConsentProvider`, and keep `ConsentDialog`, which Preferences
+opens.
+
+```svelte title="src/lib/cookie-bar.svelte"
+<script lang="ts">
+	import { getHeadlessConsent } from '@c15t/svelte';
+	import type { PresentationAction } from '@c15t/svelte';
+
+	import './cookie-bar.css';
+
+	const consent = getHeadlessConsent();
+
+	const labels: Record<PresentationAction, string> = {
+		accept: 'Accept all',
+		customize: 'Preferences',
+		dismiss: 'Got it',
+		reject: 'Reject all',
+		save: 'Save',
+	};
+
+	// The policy decides which actions this visitor gets, and in what order.
+	// Preferences has its own button, so it is always there.
+	const actions = $derived(
+		consent.banner.orderedActions.filter((action) => action !== 'customize')
+	);
+</script>
+
+{#if consent.banner.isVisible}
+	<section class="cookie-bar" aria-label="Cookie consent">
+		<p class="cookie-bar__text">
+			We use cookies to measure traffic and improve this site. Choose which ones
+			can run.
+		</p>
+		<div class="cookie-bar__actions">
+			<button
+				type="button"
+				class="cookie-bar__link"
+				onclick={() => consent.openDialog()}
+			>
+				Preferences
+			</button>
+			{#each actions as action (action)}
+				<button
+					type="button"
+					class="cookie-bar__button"
+					onclick={() => consent.performAction(action)}
+				>
+					{labels[action]}
+				</button>
+			{/each}
+		</div>
+	</section>
+{/if}
+```
+
+**HTML**
+
+The headless build, `c15t.headless.js`, keeps script gating and
+`window.c15t` and ships no banner, dialog or CSS. Buttons with
+`data-c15t-action` need no code. Because there is no stock dialog,
+Preferences opens category switches inside the bar and a Save button
+records them. Replace `https://your-project.inth.app` with the backend URL
+from your Inth project, and put the block before `</body>`.
+
+```html title="index.html"
+<script
+	src="https://your-project.inth.app/c15t.headless.js"
+	defer
+></script>
+
+<style>
+	.cookie-bar {
+		position: fixed;
+		inset: auto 0 0;
+		z-index: 50;
+		display: flex;
+		flex-wrap: wrap;
+		align-items: center;
+		gap: 0.75rem 1.5rem;
+		padding: 0.875rem 1.5rem;
+		background: #14213d;
+		color: #f8f9fb;
+		font:
+			0.9375rem/1.5 system-ui,
+			sans-serif;
+		box-shadow: 0 -4px 16px rgb(0 0 0 / 0.15);
+	}
+
+	.cookie-bar__text {
+		flex: 1 1 20rem;
+		margin: 0;
+	}
+
+	.cookie-bar__actions {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 0.5rem;
+	}
+
+	.cookie-bar button {
+		padding: 0.5rem 1rem;
+		border: 1px solid #f8f9fb;
+		border-radius: 999px;
+		background: transparent;
+		color: inherit;
+		font: inherit;
+		cursor: pointer;
+	}
+
+	.cookie-bar .cookie-bar__button {
+		background: #f8f9fb;
+		color: #14213d;
+		font-weight: 600;
+	}
+
+	.cookie-bar .cookie-bar__link {
+		border-color: transparent;
+		text-decoration: underline;
+		text-underline-offset: 3px;
+	}
+
+	.cookie-bar button:focus-visible {
+		outline: 2px solid #fca311;
+		outline-offset: 2px;
+	}
+	/* On narrow screens, Reject and Accept share a row at equal width. */
+	@media (max-width: 30rem) {
+		.cookie-bar__actions {
+			width: 100%;
+		}
+
+		.cookie-bar__actions button {
+			flex: 1 1 40%;
+		}
+
+		.cookie-bar__actions .cookie-bar__link {
+			flex-basis: 100%;
+		}
+	}
+
+	/* The headless build has no dialog, so preferences open inside the bar. */
+	.cookie-bar[hidden],
+	.cookie-bar__prefs[hidden] {
+		display: none;
+	}
+
+	.cookie-bar__prefs {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 0.5rem 1.25rem;
+		flex-basis: 100%;
+		margin: 0;
+		padding: 0;
+		border: 0;
+	}
+
+	.cookie-bar__prefs label {
+		display: flex;
+		align-items: center;
+		gap: 0.375rem;
+	}
+</style>
+
+<section
+	id="cookie-bar"
+	class="cookie-bar"
+	aria-label="Cookie consent"
+	hidden
+>
+	<p class="cookie-bar__text">
+		We use cookies to measure traffic and improve this site. Choose which
+		ones can run.
+	</p>
+	<fieldset
+		class="cookie-bar__prefs"
+		hidden
+	>
+		<legend class="cookie-bar__text">Allow these cookies:</legend>
+		<label
+			><input
+				type="checkbox"
+				name="functionality"
+			/>
+			Functionality</label
+		>
+		<label
+			><input
+				type="checkbox"
+				name="measurement"
+			/>
+			Measurement</label
+		>
+		<label
+			><input
+				type="checkbox"
+				name="experience"
+			/>
+			Experience</label
+		>
+		<label
+			><input
+				type="checkbox"
+				name="marketing"
+			/>
+			Marketing</label
+		>
+	</fieldset>
+	<div class="cookie-bar__actions">
+		<!-- c15t wires data-c15t-action buttons itself; they need no code. -->
+		<button
+			type="button"
+			class="cookie-bar__link"
+			data-c15t-action="customize"
+		>
+			Preferences
+		</button>
+		<button
+			type="button"
+			class="cookie-bar__button"
+			data-c15t-action="dismiss"
+			data-notice-only
+			hidden
+		>
+			Got it
+		</button>
+		<button
+			type="button"
+			class="cookie-bar__button"
+			data-c15t-action="reject"
+			data-choice-only
+		>
+			Reject all
+		</button>
+		<button
+			type="button"
+			class="cookie-bar__button"
+			data-c15t-action="accept"
+			data-choice-only
+		>
+			Accept all
+		</button>
+		<button
+			type="button"
+			class="cookie-bar__button"
+			data-save
+			hidden
+		>
+			Save
+		</button>
+	</div>
+</section>
+
+<script>
+	const bar = document.getElementById('cookie-bar');
+	const prefs = bar.querySelector('.cookie-bar__prefs');
+	const saveButton = bar.querySelector('[data-save]');
+	const switches = prefs.querySelectorAll('input');
+	const choiceButtons = bar.querySelectorAll('[data-choice-only]');
+	const noticeButtons = bar.querySelectorAll('[data-notice-only]');
+
+	// The tag is deferred, so queue calls until window.c15t is the real API.
+	window.c15t = window.c15t || [];
+	const queue = (call) => {
+		if (Array.isArray(window.c15t)) {
+			window.c15t.push(call);
+		} else {
+			window.c15t[call[0]](...call.slice(1));
+		}
+	};
+
+	// c15t says which surface is due; the page decides what it looks like.
+	// 'banner' shows the bar, 'dialog' opens the switches, 'none' hides it.
+	queue([
+		'on',
+		'ui',
+		(surface) => {
+			const { kind } = c15t.getSnapshot().promptRequirement;
+			const editing = surface === 'dialog';
+			// A notice gets one acknowledgement button instead of Accept and Reject.
+			for (const button of choiceButtons) {
+				button.hidden = kind === 'notice' && !editing;
+			}
+			for (const button of noticeButtons) {
+				button.hidden = kind !== 'notice' || editing;
+			}
+			for (const input of switches) {
+				input.checked = c15t.has(input.name);
+			}
+			prefs.hidden = !editing;
+			saveButton.hidden = !editing;
+			bar.hidden =
+				surface === 'none' || (surface === 'banner' && kind === 'none');
+		},
+	]);
+
+	// Save records exactly what the switches show.
+	saveButton.addEventListener('click', () => {
+		const choice = {};
+		for (const input of switches) {
+			choice[input.name] = input.checked;
+		}
+		c15t.save(choice);
+	});
+</script>
+```
+
+React, Vue and Svelte import the same stylesheet, `cookie-bar.css`. The HTML
+block contains it inline.
+
+```css title="src/cookie-bar.css"
+.cookie-bar {
+	position: fixed;
+	inset: auto 0 0;
+	z-index: 50;
+	display: flex;
+	flex-wrap: wrap;
+	align-items: center;
+	gap: 0.75rem 1.5rem;
+	padding: 0.875rem 1.5rem;
+	background: #14213d;
+	color: #f8f9fb;
+	font:
+		0.9375rem/1.5 system-ui,
+		sans-serif;
+	box-shadow: 0 -4px 16px rgb(0 0 0 / 0.15);
+}
+
+.cookie-bar__text {
+	flex: 1 1 20rem;
+	margin: 0;
+}
+
+.cookie-bar__actions {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 0.5rem;
+}
+
+.cookie-bar button {
+	padding: 0.5rem 1rem;
+	border: 1px solid #f8f9fb;
+	border-radius: 999px;
+	background: transparent;
+	color: inherit;
+	font: inherit;
+	cursor: pointer;
+}
+
+.cookie-bar .cookie-bar__button {
+	background: #f8f9fb;
+	color: #14213d;
+	font-weight: 600;
+}
+
+.cookie-bar .cookie-bar__link {
+	border-color: transparent;
+	text-decoration: underline;
+	text-underline-offset: 3px;
+}
+
+.cookie-bar button:focus-visible {
+	outline: 2px solid #fca311;
+	outline-offset: 2px;
+}
+/* On narrow screens, Reject and Accept share a row at equal width. */
+@media (max-width: 30rem) {
+	.cookie-bar__actions {
+		width: 100%;
+	}
+
+	.cookie-bar__actions button {
+		flex: 1 1 40%;
+	}
+
+	.cookie-bar__actions .cookie-bar__link {
+		flex-basis: 100%;
+	}
+}
 ```
 
-![A centered v3 choice wall with a backdrop, using the same green action theme](../assets/v3/choice-wall.png)
+On a 375-pixel screen the copy takes the full width, Preferences sits on its
+own line, and Reject all and Accept all share a row at equal width:
 
-A choice wall blocks interaction with the page. A notice never blocks; requesting
-a wall for a notice falls back to a non-blocking presentation.
+![The dark headless bar on a narrow phone screen, with the copy on two lines, a centered Preferences link, and Reject all and Accept all buttons side by side](../assets/v3/headless-bar-mobile.png)
 
-## Carry the theme into preferences
+In the HTML version, Preferences opens the switches inside the bar:
 
-![The v3 preferences dialog with optional category toggles and a green Save Settings action](../assets/v3/preferences.png)
+![The dark bar grown taller, with checkboxes for Functionality, Measurement, Experience and Marketing above Preferences, Reject all, Accept all and Save buttons](../assets/v3/headless-bar-html.png)
 
-Keep a preferences link after the banner closes. Test a reject action, reopen
-the dialog, change one category and save. A branded prompt is only part of the
-consent flow.
+A headless UI owns its focus handling and labels. Test it with a keyboard and
+a screen reader. The headless pages for [React](../frameworks/react/headless.md),
+[Vue](https://v3.c15t.com/docs/frameworks/vue/headless) and [Svelte](https://v3.c15t.com/docs/frameworks/svelte/headless)
+cover notices and custom preference forms.
 
-## Check narrow screens
+## Check a design
 
-![The branded v3 floating card at a 375-pixel viewport, with Accept and Reject sharing a row and Customize below](../assets/v3/mobile-card.png)
+Run these checks after you adopt a design:
 
-This example fits a 375-pixel viewport without horizontal overflow. Test your
-own longest translations and font settings before adopting the same sizing.
+1. Clear site data and reload. The banner appears and no optional vendor
+   request appears in DevTools Network.
+2. Click Reject all, reload, and confirm the banner stays closed and the
+   vendors stay blocked.
+3. Open preferences from your footer link, allow one category, save, and
+   confirm only that category's vendors load.
+4. Test a 375-pixel viewport with your longest translation, and tab through
+   every button.
 
-## Run the examples
+[Verify consent](../guides/verify-consent.md) has the full list.
 
-The source repository contains resettable Storybook examples under
-`Docs / Customization`: Brand Card, Brand Bar and Choice Wall. Each demo uses
-in-memory consent and no analytics; Reset example returns it to a fresh choice.
-The screenshots above come from these v3 examples.
+## Run the designs
 
-The stories are suitable for isolated iframe previews on a version-matched
-Storybook deployment. Keep source code and the explanation on this page when
-embedding them, so the recipe remains usable in Markdown and offline package
-docs. A live preview must use the same v3 revision as the documentation.
+The source repository renders each design in its Storybook under
+`Docs / Banner designs`: `apps/storybook-react`, `apps/storybook-vue`,
+`apps/storybook-svelte` and `apps/storybook-astro`. Each story uses an
+in-memory policy and loads no analytics. The HTML headless bar runs at
+`/consent-example/headless` in `internals/fixtures/script-tag`, which the example
+acceptance tests cover.