@c15t/react 2.0.0-rc.5 → 2.0.0-rc.7

package/docs/building-headless-components.md

@@ -4,9 +4,12 @@ description: Build policy-aware custom consent components in React using the hea
 ---
 Building headless components is easier now because c15t exposes policy-aware primitives instead of forcing you to reconstruct banner rules by hand.
 
+> ⚠️ **Warning:**
+> Headless is the last step in the customization ladder. Use this guide only when pre-built components, tokens, slots, compound components, and noStyle are no longer sufficient.
+
 The headless stack is:
 
-* `useHeadlessConsentUI()` for policy-aware banner/dialog actions, ordering, layout, and primary action hints
+* `useHeadlessConsentUI()` for policy-aware banner/dialog actions, ordering, layout, and primary actions hints
 * `useConsentManager()` for runtime state, categories, selected consent state, and policy metadata
 * `useTranslations()` for the resolved copy
 * `offlinePolicy.policyPacks` for offline previews that behave like backend policy resolution
@@ -24,7 +27,7 @@ The main win is that your custom UI can stay aligned with policy packs without d
 * the order those actions should render in
 * grouped actions from policy `layout`
 * layout `direction` (`row` or `column`)
-* the primary action
+* the primary actions
 * UI profile and scroll-lock hints
 * whether the banner or dialog should currently be visible
 
@@ -88,7 +91,7 @@ export function CustomConsentBanner() {
               <button
                 key={action}
                 type="button"
-                className={action === banner.primaryAction ? 'btn-primary' : 'btn-secondary'}
+                className={banner.primaryActions.includes(action) ? 'btn-primary' : 'btn-secondary'}
                 onClick={() => {
                   if (action === 'customize') {
                     openDialog();
@@ -197,7 +200,7 @@ When you build custom banner or dialog components, make sure they use:
 
 * `activeUI` or `banner.isVisible` / `dialog.isVisible` for visibility
 * `allowedActions`, `orderedActions`, or `actionGroups` instead of hard-coding buttons
-* `primaryAction` for visual emphasis
+* `primaryActions` for visual emphasis
 * `consentCategories` when deciding which category toggles to render
 * `policyDecision` when you want to debug why a specific UI state was chosen
 

package/docs/components/consent-banner.md

@@ -1,6 +1,6 @@
 ---
 title: ConsentBanner
-description: A pre-built consent banner that appears when user consent is needed. Supports custom layout, button arrangement, and full compound component composition.
+description: A pre-built consent banner that appears when user consent is needed. Supports policy-aware layout, theming, and advanced composition when markup must change.
 ---
 `ConsentBanner` is a ready-to-use consent banner that appears automatically in **opt-in jurisdictions** (like GDPR) where explicit consent is required before tracking. In opt-out jurisdictions (like CCPA), the banner won't appear — users get an opt-out mechanism instead. It includes reject, accept, and customize buttons with configurable layout.
 
@@ -18,20 +18,6 @@ export function ConsentManager() {
 }
 ```
 
-## Customizing Content
-
-Override the default title, description, and button labels:
-
-```tsx
-<ConsentBanner
-  title="We value your privacy"
-  description="We use cookies to enhance your browsing experience and analyze site traffic."
-  acceptButtonText="Accept all"
-  rejectButtonText="Reject all"
-  customizeButtonText="Manage preferences"
-/>
-```
-
 ## Button Layout
 
 The `layout` prop controls button arrangement. Each item is either a button ID or an array of button IDs (which groups them together):
@@ -86,6 +72,37 @@ Use the provider `theme` prop to control how stock consent actions look:
 
 Policy packs control grouping, ordering, and direction. The theme controls button appearance.
 
+## Styling First
+
+> ℹ️ **Info:**
+> For pure theming, stay inside the pre-built banner. Start with layout props, theme.consentActions, design tokens, and theme.slots before reaching for compound components. See Styling Overview.
+
+The stock banner maps common visual changes to the theme system:
+
+* Card background -> `theme.colors.surface`
+* Footer background -> `theme.colors.surfaceHover`
+* Card, footer, and title tweaks -> `theme.slots.consentBannerCard`, `consentBannerFooter`, and `consentBannerTitle`
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      colors: {
+        surface: '#fffdf8',
+        surfaceHover: '#f6f3ee',
+      },
+      slots: {
+        consentBannerCard: 'rounded-[28px] shadow-xl',
+        consentBannerFooter: 'border-t border-black/10 px-6',
+        consentBannerTitle: 'tracking-tight',
+      },
+    },
+  }}
+>
+  <ConsentBanner />
+</ConsentManagerProvider>
+```
+
 ### Primary Button
 
 Highlight specific button(s) as the primary action:
@@ -116,9 +133,40 @@ Control which legal links appear in the banner description:
 > ℹ️ **Info:**
 > Legal link URLs are configured in the ConsentManagerProvider options via the legalLinks prop, not on the banner itself.
 
-## Compound Components
+## Customizing Copy
+
+Prefer provider `i18n` when you want to rename the stock banner content:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    i18n: {
+      locale: 'en',
+      messages: {
+        en: {
+          cookieBanner: {
+            title: 'We value your privacy',
+            description: 'We use cookies to improve the site and measure performance.',
+          },
+          common: {
+            acceptAll: 'Accept all',
+            rejectAll: 'Reject all',
+            customize: 'Manage preferences',
+          },
+        },
+      },
+    },
+  }}
+>
+  <ConsentBanner />
+</ConsentManagerProvider>
+```
+
+Direct text props such as `title`, `description`, and `acceptButtonText` are still supported for one-off overrides, but `i18n` is the preferred path for copy changes.
 
-Build fully custom banner layouts using sub-components:
+## Advanced: Compound Components
+
+Use compound components only when the stock banner structure is no longer enough and you need to rearrange existing c15t primitives:
 
 ```tsx
 <ConsentBanner.Root>
@@ -142,7 +190,7 @@ Build fully custom banner layouts using sub-components:
 * `ConsentBanner.Root` — Outermost container, provides theme context
 * `ConsentBanner.Card` — Main content card with optional focus trapping
 * `ConsentBanner.Header` — Contains title and description
-* `ConsentBanner.Title` — Heading, defaults to translation `consentBanner.title`
+* `ConsentBanner.Title` — Heading, defaults to translation `cookieBanner.title`
 * `ConsentBanner.Description` — Description text, supports `legalLinks` prop
 * `ConsentBanner.Footer` — Action buttons container
 * `ConsentBanner.FooterSubGroup` — Groups related buttons together
@@ -151,6 +199,8 @@ Build fully custom banner layouts using sub-components:
 * `ConsentBanner.AcceptButton` — Accepts all consent
 * `ConsentBanner.Overlay` — Optional backdrop overlay
 
+If you only need styling changes, stay with tokens and slots instead of rebuilding the banner layout.
+
 ## Props
 
 ### ConsentBannerProps

package/docs/components/consent-dialog.md

@@ -81,9 +81,36 @@ Hide the c15t branding in the dialog footer:
 <ConsentDialog hideBranding />
 ```
 
-## Compound Components
+## Styling First
 
-Build fully custom dialog layouts using sub-components:
+> ℹ️ **Info:**
+> If you are only changing visuals, stay with the stock dialog and use the theme system first. Start with tokens and slots such as consentDialogCard, consentDialogHeader, and consentDialogFooter. See Styling Overview.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      colors: {
+        surface: '#fffdf8',
+        surfaceHover: '#f6f3ee',
+      },
+      slots: {
+        consentDialogCard: 'rounded-[32px] shadow-xl',
+        consentDialogHeader: 'gap-3',
+        consentDialogFooter: 'border-t border-black/10 px-6',
+      },
+    },
+  }}
+>
+  <ConsentDialog />
+</ConsentManagerProvider>
+```
+
+Dialog copy should be changed through `ConsentManagerProvider.options.i18n`, not by rebuilding the dialog structure.
+
+## Advanced: Compound Components
+
+Use compound components only when you need custom dialog markup while still keeping c15t primitives:
 
 ```tsx
 <ConsentDialog.Root>
@@ -118,6 +145,8 @@ For a quick pre-composed layout, use the shorthand card:
 </ConsentDialog.Root>
 ```
 
+If the stock dialog structure still works, prefer tokens, slots, and provider configuration instead.
+
 ## Props
 
 ### ConsentDialogProps

package/docs/components/consent-manager-provider.md

@@ -146,6 +146,7 @@ IAB TCF 2.3 configuration.
 |Property|Type|Description|Default|Required|
 |:--|:--|:--|:--|:--:|
 |enabled|boolean|Enable IAB TCF 2.3 mode. Note: Only works in 'hosted' client mode (legacy alias: 'c15t') because it requires a backend. Options: Fetch GVL from gvl.consent.io; Initialize \_\_tcfapi CMP API; Generate TC Strings for IAB compliance|-|✅ Required|
+|\_module|IABModule \|undefined|IAB runtime module injected by \`@c15t/iab\`.|-|Optional|
 |cmpId|number \|undefined|CMP ID registered with IAB Europe. When using consent.io as the backend, this is automatically provided via the \`/init\` endpoint — no client-side configuration needed. Only set this if you self-host and have your own CMP registration. A valid (non-zero) CMP ID is required for IAB TCF compliance.|-|Optional|
 |cmpVersion|string \|number \|undefined|CMP version. When omitted, defaults to package version from \`\~/cmp-defaults\` (which uses \~/version).|-|Optional|
 |vendors|number\[] \|undefined|IAB-registered vendor IDs to include (optional). Used to scope the vendor list when fetching GVL or when hosted fallback paths are used (e.g. if GVL fetch fails).|-|Optional|

package/docs/components/consent-widget.md

@@ -35,9 +35,36 @@ export function PrivacySettingsPage() {
 
 Each consent category is rendered as an expandable accordion item. Clicking the category header expands it to show a description and any associated services. Users can toggle individual categories on or off using the switch control. The `necessary` category is always enabled and cannot be toggled.
 
-## Compound Components
+## Styling First
 
-Build fully custom widget layouts using sub-components:
+> ℹ️ **Info:**
+> Most widget customization should stay in the stock component. Use theme tokens and slots such as consentWidgetAccordion, consentWidgetFooter, and toggle before reaching for compound components. See Styling Overview.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      colors: {
+        surface: '#fffdf8',
+        surfaceHover: '#f6f3ee',
+      },
+      slots: {
+        consentWidgetAccordion: 'rounded-3xl border border-black/10',
+        consentWidgetFooter: 'border-t border-black/10 px-6',
+        toggle: 'shadow-sm',
+      },
+    },
+  }}
+>
+  <ConsentWidget />
+</ConsentManagerProvider>
+```
+
+Widget copy should be changed through `ConsentManagerProvider.options.i18n` so the inline UI stays aligned with the rest of the consent experience.
+
+## Advanced: Compound Components
+
+Use compound components only when you need to rearrange the widget's existing primitives:
 
 ```tsx
 <ConsentWidget.Root>
@@ -68,6 +95,8 @@ Build fully custom widget layouts using sub-components:
 * `ConsentWidget.RejectButton` — Rejects all consent
 * `ConsentWidget.SaveButton` — Saves custom selections
 
+If the stock widget structure is already correct, stay with tokens and slots instead of rebuilding the layout.
+
 ## Props
 
 ### ConsentWidgetProps

package/docs/concepts/policy-packs.md

@@ -47,7 +47,7 @@ ui: {
     allowedActions: ['reject', 'accept', 'customize'],
     layout: [['reject', 'accept'], 'customize'],
     direction: 'row',
-    primaryAction: 'customize',
+    primaryActions: ['accept', 'customize'],
   },
 }
 ```

package/docs/headless.md

@@ -4,11 +4,12 @@ description: Build fully custom consent UI using only hooks - no pre-built compo
 ---
 c15t's headless mode means using the hooks (`useConsentManager`, `useTranslations`, etc.) without any pre-built UI components. This gives you complete control over the consent experience.
 
-There are three levels of customization:
+Before you go headless, walk the customization ladder in order:
 
-1. **Props** - Use pre-built components with custom text and configuration
-2. **noStyle** - Use pre-built components with their structure but strip all styles
-3. **Headless** - Use only hooks and build the entire UI yourself
+1. **Pre-built components** - Use provider options, component props, tokens, slots, and `theme.consentActions`
+2. **Compound components** - Rearrange c15t primitives when the markup order must change
+3. **`noStyle`** - Keep c15t structure but replace its styling
+4. **Headless** - Use only hooks and build the entire UI yourself
 
 ## When to Go Headless
 
@@ -18,10 +19,15 @@ Go headless when:
 * You need a consent flow that doesn't fit the banner/dialog pattern
 * You want to embed consent choices inline rather than as overlays
 
-Use `noStyle` instead when:
+Use a lower-power tool instead when:
 
-* The component structure works but the styling doesn't
-* You want to apply your own CSS/Tailwind without fighting defaults
+* The component structure works but the styling doesn't -> use tokens, slots, or `noStyle`
+* You only need to rearrange existing c15t parts -> use compound components
+* You want to change copy -> use `ConsentManagerProvider.options.i18n`
+* You only need to restyle stock actions -> use `theme.consentActions`
+
+> ⚠️ **Warning:**
+> Headless mode is not the first answer for pure theming. If you are still trying to debug why a banner footer color did not change, stay in the styling system and verify the token-to-component mapping before you rebuild the UI.
 
 > ℹ️ **Info:**
 > Need a policy-aware implementation guide? See Building Headless Components.

package/docs/hooks/use-consent-manager/overview.md

@@ -130,7 +130,7 @@ Policy-driven UI hints for the consent banner surface.
 |Property|Type|Description|Default|Required|
 |:--|:--|:--|:--|:--:|
 |allowedActions|PolicyUiAction \|undefined|Allowed actions for this surface derived from backend runtime policy.|-|Optional|
-|primaryAction|PolicyUiAction \|undefined|Preferred primary action hint from backend runtime policy.|-|Optional|
+|primaryActions|PolicyUiAction \|undefined|Preferred primary action hints from backend runtime policy.|-|Optional|
 |layout|PolicyUiActionGroup \|undefined|Explicit grouped action layout hint from backend runtime policy.|-|Optional|
 |direction|PolicyUiActionDirection \|undefined|Direction hint for the grouped action layout.|-|Optional|
 |uiProfile|PolicyUiProfile \|undefined|Presentation profile hint from backend runtime policy.|-|Optional|
@@ -143,7 +143,7 @@ Policy-driven UI hints for the consent dialog surface.
 |Property|Type|Description|Default|Required|
 |:--|:--|:--|:--|:--:|
 |allowedActions|PolicyUiAction \|undefined|Allowed actions for this surface derived from backend runtime policy.|-|Optional|
-|primaryAction|PolicyUiAction \|undefined|Preferred primary action hint from backend runtime policy.|-|Optional|
+|primaryActions|PolicyUiAction \|undefined|Preferred primary action hints from backend runtime policy.|-|Optional|
 |layout|PolicyUiActionGroup \|undefined|Explicit grouped action layout hint from backend runtime policy.|-|Optional|
 |direction|PolicyUiActionDirection \|undefined|Direction hint for the grouped action layout.|-|Optional|
 |uiProfile|PolicyUiProfile \|undefined|Presentation profile hint from backend runtime policy.|-|Optional|

package/docs/hooks/use-translations.md

@@ -45,6 +45,7 @@ The returned `Translations` object has these sections:
 |rejectAll|string \|undefined|-|-|✅ Required|
 |customize|string \|undefined|-|-|✅ Required|
 |save|string \|undefined|-|-|✅ Required|
+|close|string \|undefined|-|-|✅ Required|
 
 #### `cookieBanner` CookieBannerTranslations
 

package/docs/quickstart.md

@@ -33,7 +33,17 @@ availableIn:
    |yarn|`yarn add @c15t/react`|
    |bun|`bun add @c15t/react`|
 
-2. **Create ConsentManager components** Create a provider component with the consent UI and a wrapper that re-exports it. This initializes the consent store and makes consent state available to all child components.
+2. **Import styles** Import the prebuilt component stylesheet at the root of your application. This is required for styled components to render correctly.
+
+   ```tsx
+   import '@c15t/react/styles.css';
+   ```
+
+   > ℹ️ Info:
+   >
+   > If you are using the headless API or fully custom styling, you can skip this import.
+
+3. **Create ConsentManager components** Create a provider component with the consent UI and a wrapper that re-exports it. This initializes the consent store and makes consent state available to all child components.
 
    ```tsx
    'use client';
@@ -73,7 +83,7 @@ availableIn:
    >
    > Don't have a backend yet? You can use mode: 'offline' for local-only consent storage, but review the browser-only storage consequences before choosing it for production.
 
-3. **Mount ConsentManager at the app root** Wrap your existing app tree with ConsentManager so all routes/components can access consent state.
+4. **Mount ConsentManager at the app root** Wrap your existing app tree with ConsentManager so all routes/components can access consent state.
 
    ```tsx
    import { ConsentManager } from './components/consent-manager';
@@ -87,7 +97,7 @@ availableIn:
    }
    ```
 
-4. **Verify it works** Start your development server and confirm:
+5. **Verify it works** Start your development server and confirm:
 
    A consent banner appears at the bottom of the pageClicking "Customize" opens a dialog with toggles for each consent categoryAfter accepting or rejecting, the banner dismisses and your choice persists across page reloads
 

package/docs/styling/classnames.md

@@ -2,15 +2,11 @@
 title: Class Names
 description: Style consent components using className props and per-slot className targeting via the theme.
 ---
-## Component className
+## Prefer Slots for Stock Components
 
-All consent components accept a `className` prop:
+There is no single top-level `className` contract across every pre-built consent component.
 
-```tsx
-<ConsentBanner className="my-banner" />
-<ConsentDialog className="my-dialog" />
-<ConsentWidget className="my-widget" />
-```
+For the stock `ConsentBanner`, `ConsentDialog`, and `ConsentWidget`, prefer `theme.slots` first. That keeps the markup intact and lets you target the exact part you need.
 
 ## Per-Slot className
 
@@ -59,9 +55,19 @@ const theme = {
 }
 ```
 
-## noStyle Mode
+## When to Use Raw className
+
+Use raw className-level styling when:
+
+* your styling system is already class-driven
+* tokens are too broad for the change
+* slots already identify the correct element
 
-Use `noStyle` when you want to remove defaults and style from scratch:
+If the request is "make the banner footer darker", prefer `theme.colors.surfaceHover` first. If the request is "add a border and spacing only to the footer", prefer `theme.slots.consentBannerFooter`.
+
+## Advanced: `noStyle`
+
+Use `noStyle` only when you want to remove defaults and style from scratch while still keeping c15t's component structure:
 
 ```tsx
 {/* Remove all styles from a specific component */}
@@ -81,4 +87,6 @@ const theme = {
 } satisfies Theme;
 ```
 
+Treat `noStyle` as an advanced escape hatch. Do not jump to it just because a token or slot needs debugging.
+
 For full custom markup and behavior, continue to [Headless Mode](../headless).