@c15t/nextjs 2.1.0 → 2.2.1

package/docs/frameworks/next/styling/overview.md

@@ -0,0 +1,299 @@
+---
+title: Styling Overview
+description: Five approaches for theming consent components — design tokens,
+  component slots, CSS variables, className, and noStyle mode.
+group: frameworks
+---
+c15t's theming system gives you multiple levels of control, but most customization should stay inside the pre-built components.
+
+Start with the lowest-power tool that solves the problem:
+
+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 (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
+
+```tsx
+import { type Theme, ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/nextjs';
+
+const theme = {
+  colors: {
+    primary: '#6366f1',
+    primaryHover: '#4f46e5',
+  },
+  radius: {
+    md: '0.75rem',
+    lg: '1rem',
+  },
+  slots: {
+    consentBannerTitle: 'text-xl font-semibold',
+    buttonPrimary: 'rounded-full',
+  },
+} satisfies Theme;
+
+export function ConsentManager({ children }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        theme,
+      }}
+    >
+      <ConsentBanner />
+      <ConsentDialog />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## 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" />
+```
+
+### 2. Design tokens
+
+Set global values for colors, typography, spacing, radius, shadows, and motion:
+
+```tsx
+options={{ theme: { colors: { primary: '#6366f1' } } }}
+```
+
+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`
+* Primary-filled surfaces such as stock branding tags and filled actions -> `theme.colors.primary` with `theme.colors.textOnPrimary` as the matching foreground override
+
+```tsx
+options={{
+  theme: {
+    colors: {
+      surface: '#ffffff',
+      surfaceHover: '#f6f3ee',
+    },
+  },
+}}
+```
+
+If you set `theme.colors.primary` but omit `theme.colors.textOnPrimary`, c15t derives a readable foreground automatically. Add `textOnPrimary` only when you need to force a specific branded foreground color.
+
+### 3. Component slots
+
+Target specific component parts via the `slots` object:
+
+```tsx
+options={{
+  theme: {
+    slots: {
+      consentBannerCard: 'rounded-[28px] shadow-xl',
+      consentBannerFooter: 'border-t border-black/10',
+      consentBannerTitle: 'tracking-tight',
+    },
+  },
+}}
+```
+
+Use slots when the component part is right but the local styling needs adjustment.
+
+### 4. CSS variables and className-level overrides
+
+Override `--c15t-*` custom properties in your stylesheet or attach classes through slots when your app styling is driven externally.
+
+Reach for this after tokens and slots, not before.
+
+```tsx
+options={{
+  theme: {
+    slots: {
+      consentBannerFooter: 'bg-[var(--banner-footer)]',
+    },
+  },
+}}
+```
+
+## Escalating Beyond Pre-Built Components
+
+Only move up this ladder when the lower rung cannot satisfy the request.
+
+### 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 the banner footer background
+
+```tsx
+options={{
+  theme: {
+    colors: {
+      surfaceHover: '#f6f3ee',
+    },
+  },
+}}
+```
+
+Use `theme.colors.surfaceHover` before trying raw CSS.
+
+### Change the banner card background
+
+```tsx
+options={{
+  theme: {
+    colors: {
+      surface: '#fffdf8',
+    },
+  },
+}}
+```
+
+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: {
+      consentBannerCard: 'rounded-[28px] shadow-xl',
+      consentBannerFooter: 'border-t border-black/10 px-6',
+      consentBannerTitle: 'text-xl tracking-tight',
+    },
+  },
+}}
+```
+
+### Change stock consent action button styles semantically
+
+```tsx
+options={{
+  theme: {
+    consentActions: {
+      default: { mode: 'stroke' },
+      accept: { variant: 'primary', mode: 'stroke' },
+      customize: { variant: 'neutral', mode: 'ghost' },
+    },
+  },
+}}
+```
+
+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
+options={{
+  colorScheme: 'system',
+  theme: {
+    colors: { surface: '#ffffff', text: '#1f2937' },
+    dark: { surface: '#111827', text: '#f9fafb' },
+  },
+}}
+```
+
+> ℹ️ **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:**
+> 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
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`Theme\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "Theme" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/frameworks/next/styling/slots.md

@@ -0,0 +1,94 @@
+---
+title: Component Slots
+description: Target individual component parts with styles using the slot system
+  - className strings or inline style objects.
+group: frameworks
+---
+## What are Slots?
+
+Slots let you target specific parts of consent components with styles. Each component is built from named slots such as `consentBannerTitle` and `consentDialogTag`.
+
+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
+
+Pass slot styles in the theme's `slots` object:
+
+```tsx
+const theme = {
+  slots: {
+    consentBannerFooter: 'border-t border-black/10 px-6',
+    consentBannerTitle: 'text-xl font-bold tracking-tight',
+
+    // Object value = className + inline styles
+    consentBannerCard: {
+      className: 'rounded-xl shadow-lg',
+      style: { maxWidth: '600px' },
+    },
+  },
+} satisfies Theme;
+```
+
+## Slot Style Types
+
+Each slot accepts either a `string` (treated as className) or a `SlotStyle` object:
+
+```tsx
+// String: treated as className
+consentBannerTitle: 'my-custom-class'
+
+// Object: className + style + noStyle
+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.
+
+## API Reference
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ComponentSlots\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ComponentSlots" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`SlotStyle\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "SlotStyle" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/{styling → frameworks/next/styling}/tailwind.md

@@ -1,6 +1,8 @@
 ---
 title: Tailwind CSS
-description: Use Tailwind CSS utility classes to style consent components via the slot system.
+description: Use Tailwind CSS utility classes to style consent components via
+  the slot system.
+group: frameworks
 ---
 c15t works with Tailwind CSS out of the box. Use the `slots` theme option to apply Tailwind utility classes to any component part.
 

package/docs/frameworks/next/styling/tokens.md

@@ -0,0 +1,156 @@
+---
+title: Design Tokens
+description: The six base token categories that control colors, typography,
+  spacing, radius, shadows, and motion, plus optional dark-mode overrides.
+group: frameworks
+---
+## Color Tokens
+
+Color tokens define the palette for all consent components. Set `colors` for light mode and `dark` for dark mode overrides.
+
+When `textOnPrimary` is omitted, c15t derives it automatically from `primary` to keep text readable on primary-filled surfaces such as stock branding tags and buttons. Set `textOnPrimary` explicitly when you need a specific foreground color.
+
+```tsx
+const theme = {
+  colors: {
+    primary: '#6366f1',
+    primaryHover: '#4f46e5',
+    surface: '#ffffff',
+    surfaceHover: '#f9fafb',
+    border: '#e5e7eb',
+    borderHover: '#d1d5db',
+    text: '#1f2937',
+    textMuted: '#6b7280',
+    textOnPrimary: '#ffffff',
+    overlay: 'rgba(0, 0, 0, 0.5)',
+    switchTrack: '#d1d5db',
+    switchTrackActive: '#6366f1',
+    switchThumb: '#ffffff',
+  },
+  dark: {
+    primary: '#818cf8',
+    surface: '#1f2937',
+    text: '#f9fafb',
+    textMuted: '#9ca3af',
+    border: '#374151',
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ColorTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ColorTokens" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+## Typography Tokens
+
+Control font family, sizes, weights, and line heights.
+
+```tsx
+const theme = {
+  typography: {
+    fontFamily: 'Inter, system-ui, sans-serif',
+    fontSize: { sm: '0.875rem', base: '1rem', lg: '1.125rem' },
+    fontWeight: { normal: 400, medium: 500, semibold: 600 },
+    lineHeight: { tight: '1.25', normal: '1.5', relaxed: '1.75' },
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`TypographyTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "TypographyTokens" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+## Spacing Tokens
+
+Five-step scale for internal padding, margins, and gaps.
+
+```tsx
+const theme = {
+  spacing: {
+    xs: '0.25rem',  // 4px
+    sm: '0.5rem',   // 8px
+    md: '1rem',     // 16px
+    lg: '1.5rem',   // 24px
+    xl: '2rem',     // 32px
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`SpacingTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "SpacingTokens" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+## Radius Tokens
+
+Border radius scale for rounded corners.
+
+```tsx
+const theme = {
+  radius: {
+    sm: '0.25rem',  // 4px
+    md: '0.5rem',   // 8px
+    lg: '0.75rem',  // 12px
+    full: '9999px', // Pill shape
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`RadiusTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "RadiusTokens" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+## Shadow Tokens
+
+Box shadow scale for depth and elevation.
+
+```tsx
+const theme = {
+  shadows: {
+    sm: '0 1px 2px hsla(0, 0%, 0%, 0.05)',
+    md: '0 4px 12px hsla(0, 0%, 0%, 0.08)',
+    lg: '0 8px 24px hsla(0, 0%, 0%, 0.12)',
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ShadowTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ShadowTokens" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+## Motion Tokens
+
+Animation duration and easing presets.
+
+```tsx
+const theme = {
+  motion: {
+    duration: { fast: '100ms', normal: '200ms', slow: '300ms' },
+    easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
+    easingOut: 'cubic-bezier(0.215, 0.61, 0.355, 1)',
+    easingInOut: 'cubic-bezier(0.645, 0.045, 0.355, 1)',
+    easingSpring: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`MotionTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "MotionTokens" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/{troubleshooting.md → frameworks/next/troubleshooting.md}

@@ -1,6 +1,8 @@
 ---
 title: Troubleshooting
-description: Solutions for common issues with @c15t/nextjs — provider errors, missing banners, consent persistence, and more.
+description: Solutions for common issues with @c15t/nextjs — provider errors,
+  missing banners, consent persistence, and more.
+group: frameworks
 ---
 ## "Provider not found" Error