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

package/docs/styling/overview.md

@@ -2,24 +2,34 @@
 title: Styling Overview
 description: Customize every aspect of c15t's consent components using design tokens, component slots, and CSS variables.
 ---
-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
 
@@ -61,9 +71,25 @@ export function ConsentManager({ children }: { children: ReactNode }) {
 }
 ```
 
-## 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:
 
@@ -71,55 +97,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={{
@@ -135,6 +246,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
@@ -147,8 +281,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

@@ -18,40 +18,32 @@ import '@c15t/nextjs/styles.css';
 
 ### 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. 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;
 @import "tailwindcss";
 ```
 
 ### 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:
+Import the Tailwind 3-compatible c15t stylesheet before your app Tailwind globals, then keep your standard Tailwind directives in the app stylesheet:
 
-```css title="app/globals.css"
-@layer base, components, c15t;
+```tsx title="app/layout.tsx"
+import '@c15t/react/styles.tw3.css';
+import './globals.css';
+```
 
-@layer base {
-  @tailwind base;
-}
+```tsx title="app/layout.tsx"
+import '@c15t/nextjs/styles.tw3.css';
+import './globals.css';
+```
 
+```css title="app/globals.css"
+@tailwind base;
 @tailwind components;
 @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}',
-  ],
-};
-```
-
 ## Using Tailwind with Slots
 
 Apply Tailwind classes via the theme's `slots` object:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@c15t/react",
-	"version": "2.0.0-rc.6",
+	"version": "2.0.0-rc.7",
 	"description": "Developer-first CMP for React: cookie banner, consent manager, preferences centre. GDPR ready with minimal setup and rich customization",
 	"keywords": [
 		"react",
@@ -32,7 +32,9 @@
 	"type": "module",
 	"exports": {
 		"./styles.css": "./dist/styles.css",
+		"./styles.tw3.css": "./src/styles.tw3.css",
 		"./iab/styles.css": "./dist/iab/styles.css",
+		"./iab/styles.tw3.css": "./src/iab/styles.tw3.css",
 		"./primitives": {
 			"types": "./dist/primitives.d.ts",
 			"import": "./dist/primitives.js",
@@ -137,6 +139,8 @@
 		"docs",
 		"dist-types",
 		"client",
+		"src/styles.tw3.css",
+		"src/iab/styles.tw3.css",
 		"!dist/mockServiceWorker.js"
 	],
 	"scripts": {
@@ -158,7 +162,7 @@
 		"not op_mini all"
 	],
 	"dependencies": {
-		"@c15t/ui": "2.0.0-rc.6",
+		"@c15t/ui": "2.0.0-rc.7",
 		"c15t": "2.0.0-rc.6",
 		"clsx": "2.1.1"
 	},

package/src/iab/styles.tw3.css

@@ -0,0 +1,10 @@
+/**
+ * @c15t/react/iab — Tailwind 3-compatible IAB component styles.
+ *
+ * Import this stylesheet before your app Tailwind globals so utility classes
+ * can come after the c15t base rules.
+ *
+ * Usage:
+ *   import '@c15t/react/iab/styles.tw3.css';
+ */
+@import "@c15t/ui/iab/styles.tw3.css";

package/src/styles.tw3.css

@@ -0,0 +1,10 @@
+/**
+ * @c15t/react — Tailwind 3-compatible prebuilt component styles.
+ *
+ * Import this stylesheet before your app Tailwind globals so utility classes
+ * can come after the c15t base rules.
+ *
+ * Usage:
+ *   import '@c15t/react/styles.tw3.css';
+ */
+@import "@c15t/ui/styles.tw3.css";