@c15t/nextjs 2.0.0-rc.6 → 2.0.0-rc.8

package/docs/styling/overview.md

@@ -2,24 +2,34 @@
 title: Styling Overview
 description: Five approaches for theming consent components — design tokens, component slots, CSS variables, className, and noStyle mode.
 ---
-c15t's theming system gives you multiple levels of control, from high-level design tokens to complete style removal.
+c15t's theming system gives you multiple levels of control, but most customization should stay inside the pre-built components.
 
-The flow:
+Start with the lowest-power tool that solves the problem:
 
-1. **Define** tokens (colors, spacing, radius, etc.) in JavaScript
-2. Tokens are **injected** as CSS custom properties (`--c15t-*`) at runtime
-3. Components **consume** these variables in their default styles
-4. You **override** at any level: tokens, slots, CSS variables, or raw classNames
+1. **Pre-built component APIs** — provider options and component props such as `layout`, `direction`, `primaryButton`, `legalLinks`, and `theme.consentActions`
+2. **Design tokens** — global colors, typography, spacing, radius, shadows, and motion
+3. **Slots** — targeted styling for specific parts such as the banner card, footer, or title
+4. **CSS variables or className-level overrides** — when you need to integrate with external CSS systems
+5. **Compound components** — when you must rearrange markup while still using c15t primitives
+6. **`noStyle`** — when you want c15t structure but you need to own all visual styling
+7. **Headless** — when you want fully custom markup and behavior
+
+Keep styling and escalation as separate decisions:
+
+* If you are still using the stock banner, dialog, or widget, stay with props, tokens, and slots.
+* Escalate to compound components, `noStyle`, or headless only when the structure or behavior itself must change.
 
 ## Styling Approaches
 
 |Approach|Control|Use When|
 |--|--|--|
+|**Component and provider APIs**|High|Reordering actions, changing button emphasis, configuring links, hiding branding, changing copy via `i18n`|
 |**Tokens**|High|Changing global colors, typography, spacing, radius, shadows, or motion|
-|**Slots**|Medium|Targeting specific component parts (e.g., the banner title, dialog footer)|
-|**CSS Variables**|Medium|Overriding `--c15t-*` variables from external CSS|
-|**className**|Medium|Passing class names to components or slots|
-|**noStyle**|Full|Removing all default styles, building from scratch|
+|**Slots**|Medium|Targeting specific component parts (for example `consentBannerFooter` or `consentDialogCard`)|
+|**CSS variables / className**|Medium|Integrating with an existing stylesheet or utility classes after tokens and slots|
+|**Compound components**|Structure|Rearranging existing c15t primitives without going fully custom|
+|**noStyle**|Full visuals|Keeping c15t structure but replacing all visual defaults|
+|**Headless**|Full|Replacing both markup and behavior|
 
 ## Quick Start
 
@@ -58,9 +68,25 @@ export function ConsentManager({ children }) {
 }
 ```
 
-## Styling Paths
+## Styling Inside Pre-Built Components
+
+Start here before you consider compound components or headless mode.
+
+### 1. Provider and component configuration
+
+Use the stock APIs first:
+
+* `layout`, `direction`, and `primaryButton` for banner action arrangement
+* `legalLinks` for link visibility
+* `hideBranding` and `showTrigger` for dialog and widget behavior
+* `theme.consentActions` for stock banner and dialog button treatment
+* `i18n` on `ConsentManagerProvider` for copy changes
+
+```tsx
+<ConsentBanner layout={['customize', ['reject', 'accept']]} primaryButton="accept" />
+```
 
-### 1. Design tokens
+### 2. Design tokens
 
 Set global values for colors, typography, spacing, radius, shadows, and motion:
 
@@ -68,55 +94,140 @@ Set global values for colors, typography, spacing, radius, shadows, and motion:
 options={{ theme: { colors: { primary: '#6366f1' } } }}
 ```
 
-### 2. Component slots
+Use tokens first when the change is semantic:
+
+* Banner card background -> `theme.colors.surface`
+* Banner footer background -> `theme.colors.surfaceHover`
+* Shared copy color -> `theme.colors.text` and `theme.colors.textMuted`
+
+```tsx
+options={{
+  theme: {
+    colors: {
+      surface: '#ffffff',
+      surfaceHover: '#f6f3ee',
+    },
+  },
+}}
+```
+
+### 3. Component slots
 
 Target specific component parts via the `slots` object:
 
 ```tsx
-options={{ theme: { slots: { consentBannerTitle: 'text-2xl font-bold' } } }}
+options={{
+  theme: {
+    slots: {
+      consentBannerCard: 'rounded-[28px] shadow-xl',
+      consentBannerFooter: 'border-t border-black/10',
+      consentBannerTitle: 'tracking-tight',
+    },
+  },
+}}
 ```
 
-### 3. CSS variables
+Use slots when the component part is right but the local styling needs adjustment.
 
-Override `--c15t-*` custom properties in your stylesheet.
+### 4. CSS variables and className-level overrides
 
-### 4. className prop
+Override `--c15t-*` custom properties in your stylesheet or attach classes through slots when your app styling is driven externally.
 
-Pass className directly to components:
+Reach for this after tokens and slots, not before.
 
 ```tsx
-<ConsentBanner className="my-custom-banner" />
+options={{
+  theme: {
+    slots: {
+      consentBannerFooter: 'bg-[var(--banner-footer)]',
+    },
+  },
+}}
 ```
 
-### 5. noStyle prop
+## Escalating Beyond Pre-Built Components
+
+Only move up this ladder when the lower rung cannot satisfy the request.
 
-Strip all default styles and build from scratch (best paired with [Headless Mode](../headless)):
+### 5. Compound components
+
+Use compound components when you need to rearrange existing c15t primitives:
+
+```tsx
+<ConsentBanner.Root>
+  <ConsentBanner.Card>
+    <ConsentBanner.Header>
+      <ConsentBanner.Title />
+      <ConsentBanner.Description />
+    </ConsentBanner.Header>
+    <ConsentBanner.Footer>
+      <ConsentBanner.CustomizeButton />
+      <ConsentBanner.FooterSubGroup>
+        <ConsentBanner.RejectButton />
+        <ConsentBanner.AcceptButton />
+      </ConsentBanner.FooterSubGroup>
+    </ConsentBanner.Footer>
+  </ConsentBanner.Card>
+</ConsentBanner.Root>
+```
+
+### 6. `noStyle`
+
+Use `noStyle` only when the c15t structure is still correct but you want to replace all visual defaults:
 
 ```tsx
 <ConsentBanner noStyle />
 ```
 
+### 7. Headless
+
+Go headless only when you are replacing both markup and behavior. For that path, continue to [Headless Mode](../headless).
+
 ## Common Styling Tasks
 
-### Change brand color globally
+### Change the banner footer background
 
 ```tsx
-options={{ theme: { colors: { primary: '#0ea5e9', primaryHover: '#0284c7' } } }}
+options={{
+  theme: {
+    colors: {
+      surfaceHover: '#f6f3ee',
+    },
+  },
+}}
 ```
 
-### Make the banner card more compact
+Use `theme.colors.surfaceHover` before trying raw CSS.
+
+### Change the banner card background
 
 ```tsx
-options={{ theme: { spacing: { md: '0.75rem', lg: '1rem' } } }}
+options={{
+  theme: {
+    colors: {
+      surface: '#fffdf8',
+    },
+  },
+}}
 ```
 
-### Round primary/secondary buttons
+Use `theme.colors.surface` before overriding banner CSS variables directly.
+
+### Tweak the banner card, footer, or title styling without changing markup
 
 ```tsx
-options={{ theme: { slots: { buttonPrimary: 'rounded-full', buttonSecondary: 'rounded-full' } } }}
+options={{
+  theme: {
+    slots: {
+      consentBannerCard: 'rounded-[28px] shadow-xl',
+      consentBannerFooter: 'border-t border-black/10 px-6',
+      consentBannerTitle: 'text-xl tracking-tight',
+    },
+  },
+}}
 ```
 
-### Change consent action button styles semantically
+### Change stock consent action button styles semantically
 
 ```tsx
 options={{
@@ -132,6 +243,29 @@ options={{
 
 Use `theme.consentActions` when you want to change the stock banner/dialog button treatment without rewriting the component layout. Policy packs still control action arrangement and primary-action hints. The theme controls whether those actions render as `stroke`, `filled`, `ghost`, or `lighter`.
 
+### Change banner copy without replacing the component
+
+```tsx
+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',
+        },
+      },
+    },
+  },
+}}
+```
+
 ### Enable dark mode safely
 
 ```tsx
@@ -144,8 +278,11 @@ options={{
 }}
 ```
 
+> ℹ️ **Info:**
+> If a token change does not show up where you expect, check how that component maps tokens to CSS variables before escalating. For example, the stock banner footer background comes from colors.surfaceHover, not a separate footer token.
+>
 > ⚠️ **Warning:**
-> noStyle: true removes layout and visual defaults. Use it only when you want full control.Use either tokens/slots or raw CSS variable overrides intentionally to avoid conflicting style sources.For dark mode, c15t supports .dark and .c15t-dark.
+> Do not jump to CSS overrides or !important because a token did not appear to work at first glance.noStyle: true removes layout and visual defaults. Treat it as an advanced opt-out, not a normal theming step.Headless mode is for replacing markup and behavior, not for styling-only requests.Use either tokens/slots or raw CSS variable overrides intentionally to avoid conflicting style sources.For dark mode, c15t supports .dark and .c15t-dark.
 
 ## API Reference
 

package/docs/styling/slots.md

@@ -4,7 +4,19 @@ description: Target individual component parts with styles using the slot system
 ---
 ## What are Slots?
 
-Slots let you target specific parts of consent components with styles. Each component is built from named "slots" (e.g., `consentBannerTitle`, `consentDialogFooter`) that you can style individually.
+Slots let you target specific parts of consent components with styles. Each component is built from named slots such as `consentBannerTitle` and `consentDialogFooter`.
+
+Use slots after the stock component APIs and design tokens:
+
+* If the change is semantic, prefer tokens first. For example, the stock banner footer background comes from `theme.colors.surfaceHover`.
+* If the component part is correct but you need a local tweak, use a slot.
+
+Common banner slot choices:
+
+* `consentBannerCard` for card radius, shadow, width, and local background treatment
+* `consentBannerFooter` for spacing, borders, and local footer styling
+* `consentBannerTitle` for title typography
+* `buttonPrimary` and `buttonSecondary` for shared button classes
 
 ## Using Slots
 
@@ -13,8 +25,8 @@ Pass slot styles in the theme's `slots` object:
 ```tsx
 const theme = {
   slots: {
-    // String value = className
-    consentBannerTitle: 'text-xl font-bold text-gray-900',
+    consentBannerFooter: 'border-t border-black/10 px-6',
+    consentBannerTitle: 'text-xl font-bold tracking-tight',
 
     // Object value = className + inline styles
     consentBannerCard: {
@@ -34,13 +46,31 @@ Each slot accepts either a `string` (treated as className) or a `SlotStyle` obje
 consentBannerTitle: 'my-custom-class'
 
 // Object: className + style + noStyle
-consentBannerTitle: {
-  className: 'my-custom-class',
-  style: { color: 'red', fontSize: '1.5rem' },
-  noStyle: false, // Set true to remove default styles for this slot
+consentBannerFooter: {
+  className: 'border-t border-black/10',
+  style: { paddingBlock: '1rem' },
+  noStyle: false, // Set true only when you want to remove this slot's default styling
 }
 ```
 
+`noStyle` on a slot is an advanced escape hatch. Start with className and style overrides first.
+
+## Example: Style the stock banner without changing markup
+
+```tsx
+const theme = {
+  colors: {
+    surface: '#fffdf8',
+    surfaceHover: '#f6f3ee',
+  },
+  slots: {
+    consentBannerCard: 'rounded-[28px] shadow-xl',
+    consentBannerFooter: 'border-t border-black/10 px-6',
+    consentBannerTitle: 'tracking-tight',
+  },
+} satisfies Theme;
+```
+
 ## Available Slots
 
 Use the typed API reference below for the full slot list and descriptions. It stays in sync with the actual component slot surface.

package/docs/styling/tailwind.md

@@ -6,50 +6,48 @@ c15t works with Tailwind CSS out of the box. Use the `slots` theme option to app
 
 ## Setup
 
-Import the standard c15t stylesheet once at the root of your app:
+Import the standard c15t stylesheet once in your app-level CSS entrypoint:
 
-```tsx
-// React
-import '@c15t/react/styles.css';
+```css
+/* React: src/index.css */
+@import "@c15t/react/styles.css";
 
-// Next.js
-import '@c15t/nextjs/styles.css';
+/* Next.js: app/globals.css */
+@import "@c15t/nextjs/styles.css";
 ```
 
+Keeping the c15t stylesheet in your global CSS entrypoint makes layer and cascade order explicit. JS/TSX side-effect imports can load in a different order across framework and Tailwind tooling, which makes style regressions harder to debug.
+
 ### Tailwind v4
 
-Tailwind v4 automatically scans your source files. Declare c15t's layer order once in your global CSS so utilities stay last:
+Tailwind v4 automatically scans your source files. Import Tailwind normally, then place the c15t stylesheet immediately after it. c15t component styles join Tailwind's `components` layer automatically, so no extra c15t-specific layer declaration is needed:
 
-```css
-@layer theme, base, components, c15t, utilities;
+```css title="src/index.css"
 @import "tailwindcss";
+@import "@c15t/react/styles.css";
 ```
 
-### Tailwind v3
-
-Keep Tailwind's directives in your app stylesheet, but wrap `@tailwind base` in a native `base` layer so c15t's `@layer c15t` rules can sit above Preflight:
-
 ```css title="app/globals.css"
-@layer base, components, c15t;
+@import "tailwindcss";
+@import "@c15t/nextjs/styles.css";
+```
 
-@layer base {
-  @tailwind base;
-}
+### Tailwind v3
+
+Import the Tailwind 3-compatible c15t stylesheet after `@tailwind components;` and before `@tailwind utilities;`:
 
+```css title="src/index.css"
+@tailwind base;
 @tailwind components;
+@import "@c15t/react/styles.tw3.css";
 @tailwind utilities;
 ```
 
-Then add c15t's component paths to your `content` array:
-
-```js title="tailwind.config.js"
-module.exports = {
-  content: [
-    './src/**/*.{js,ts,jsx,tsx}',
-    './node_modules/@c15t/react/**/*.{js,mjs}',
-    './node_modules/@c15t/nextjs/**/*.{js,mjs}',
-  ],
-};
+```css title="app/globals.css"
+@tailwind base;
+@tailwind components;
+@import "@c15t/nextjs/styles.tw3.css";
+@tailwind utilities;
 ```
 
 ## Using Tailwind with Slots

package/iab/styles.css

@@ -0,0 +1 @@
+@import "../dist/iab/styles.css";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@c15t/nextjs",
-	"version": "2.0.0-rc.6",
+	"version": "2.0.0-rc.8",
 	"description": "Developer-first CMP for Next.js: cookie banner, consent manager, preferences centre. GDPR ready with minimal setup and rich customization.",
 	"keywords": [
 		"nextjs",
@@ -33,7 +33,9 @@
 	"type": "module",
 	"exports": {
 		"./styles.css": "./dist/styles.css",
+		"./styles.tw3.css": "./dist/styles.tw3.css",
 		"./iab/styles.css": "./dist/iab/styles.css",
+		"./iab/styles.tw3.css": "./dist/iab/styles.tw3.css",
 		"./headless": {
 			"types": "./dist-types/headless.d.ts",
 			"import": "./dist/headless.js",
@@ -57,14 +59,20 @@
 		"dist",
 		"docs",
 		"dist-types",
-		"client"
+		"client",
+		"styles.css",
+		"iab",
+		"src/styles.css",
+		"src/styles.tw3.css",
+		"src/iab/styles.css",
+		"src/iab/styles.tw3.css"
 	],
 	"scripts": {
 		"prebuild": "genversion --esm --semi src/version.ts",
-		"build": "bun prebuild && rslib build && bun ../../scripts/agent-docs/generate-package-docs.ts @c15t/nextjs",
+		"build": "bun prebuild && rslib build && bun ../../scripts/normalize-dist-types.mjs && bun scripts/generate-distribution-css.ts && bun ../../scripts/agent-docs/generate-package-docs.ts @c15t/nextjs",
 		"build:agent-docs": "bun ../../scripts/agent-docs/generate-package-docs.ts @c15t/nextjs",
 		"check-types": "bun prebuild && tsc --noEmit",
-		"dev": "bun prebuild && rslib build",
+		"dev": "bun prebuild && rslib build && bun ../../scripts/normalize-dist-types.mjs && bun scripts/generate-distribution-css.ts",
 		"fmt": "bun biome format --write . && bun biome check --formatter-enabled=false --linter-enabled=false --write",
 		"lint": "bun biome lint ./src",
 		"prepack": "cd ../.. && bunx turbo run build --filter=@c15t/nextjs",
@@ -72,9 +80,9 @@
 		"test:watch": "bun prebuild && vitest --passWithNoTests"
 	},
 	"dependencies": {
-		"@c15t/react": "2.0.0-rc.6",
-		"@c15t/translations": "2.0.0-rc.5",
-		"c15t": "2.0.0-rc.6"
+		"@c15t/react": "2.0.0-rc.8",
+		"@c15t/translations": "2.0.0-rc.8",
+		"c15t": "2.0.0-rc.8"
 	},
 	"devDependencies": {
 		"@c15t/typescript-config": "0.0.1-beta.1",

package/readme.json

@@ -21,6 +21,10 @@
 		"",
 		"```bash\npnpm add @c15t/nextjs\n```",
 		"",
+		"Then add the prebuilt stylesheet to your app-level CSS entrypoint:",
+		"",
+		"```css\n/* app/globals.css */\n@import \"@c15t/nextjs/styles.css\";\n```",
+		"",
 		"To manually install, follow the guide in our [docs – manual setup](https://c15t.com/docs/frameworks/nextjs/quickstart#manual-setup)."
 	],
 	"usage": [

package/src/iab/styles.css

@@ -0,0 +1,12 @@
+/**
+ * @c15t/nextjs — IAB TCF component styles.
+ *
+ * Add this stylesheet to the same global CSS entrypoint as your base c15t styles
+ * when using IAB consent components in Next.js. Do not import either stylesheet
+ * from JS/TSX.
+ *
+ * Usage (app/globals.css):
+ *   @import "@c15t/nextjs/styles.css";
+ *   @import "@c15t/nextjs/iab/styles.css";
+ */
+@import "@c15t/react/iab/styles.css";

package/src/iab/styles.tw3.css

@@ -0,0 +1,14 @@
+/**
+ * @c15t/nextjs/iab — Tailwind 3-compatible IAB component styles.
+ *
+ * Add this stylesheet to the same global CSS entrypoint as your base c15t styles.
+ * Do not import either stylesheet from JS/TSX files.
+ *
+ * Usage (app/globals.css):
+ *   @tailwind base;
+ *   @tailwind components;
+ *   @import "@c15t/nextjs/styles.tw3.css";
+ *   @import "@c15t/nextjs/iab/styles.tw3.css";
+ *   @tailwind utilities;
+ */
+@import "@c15t/react/iab/styles.tw3.css";

package/src/styles.css

@@ -0,0 +1,10 @@
+/**
+ * @c15t/nextjs — Non-IAB prebuilt component styles.
+ *
+ * Import this stylesheet once from your app-level CSS entrypoint when using
+ * prebuilt (styled) consent components.
+ *
+ * Usage (app/globals.css):
+ *   @import "@c15t/nextjs/styles.css";
+ */
+@import "@c15t/react/styles.css";

package/src/styles.tw3.css

@@ -0,0 +1,13 @@
+/**
+ * @c15t/nextjs — Tailwind 3-compatible prebuilt component styles.
+ *
+ * Import this stylesheet in the same global CSS entrypoint as Tailwind 3,
+ * after `@tailwind components;` and before `@tailwind utilities;`.
+ *
+ * Usage (app/globals.css):
+ *   @tailwind base;
+ *   @tailwind components;
+ *   @import "@c15t/nextjs/styles.tw3.css";
+ *   @tailwind utilities;
+ */
+@import "@c15t/react/styles.tw3.css";

package/styles.css

@@ -0,0 +1 @@
+@import "./dist/styles.css";