@c15t/react 2.0.0-rc.0 → 2.0.0-rc.10

package/docs/styling/css-variables.md

@@ -0,0 +1,92 @@
+---
+title: CSS Variables
+description: Reference for all --c15t-* CSS custom properties generated by the theme system.
+---
+Every theme token is converted to a `--c15t-*` CSS custom property at runtime. You can override these variables in your stylesheet without using the JavaScript theme API.
+
+## Variable Reference
+
+### ThemeCSSVariables
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|--c15t-primary|string \|undefined|\`colors.primary\` (default: \`hsl(228, 100%, 60%)\`)|-|Optional|
+|--c15t-primary-hover|string \|undefined|\`colors.primaryHover\` (default: \`hsl(228, 100%, 55%)\`)|-|Optional|
+|--c15t-surface|string \|undefined|\`colors.surface\` (default: \`hsl(0, 0%, 100%)\`)|-|Optional|
+|--c15t-surface-hover|string \|undefined|\`colors.surfaceHover\` (default: \`hsl(0, 0%, 98%)\`)|-|Optional|
+|--c15t-border|string \|undefined|\`colors.border\` (default: \`hsl(0, 0%, 90%)\`)|-|Optional|
+|--c15t-border-hover|string \|undefined|\`colors.borderHover\` (default: \`hsl(0, 0%, 85%)\`)|-|Optional|
+|--c15t-text|string \|undefined|\`colors.text\` (default: \`hsl(0, 0%, 10%)\`)|-|Optional|
+|--c15t-text-muted|string \|undefined|\`colors.textMuted\` (default: \`hsl(0, 0%, 40%)\`)|-|Optional|
+|--c15t-text-on-primary|string \|undefined|\`colors.textOnPrimary\` (auto-derived from \`colors.primary\` when omitted)|-|Optional|
+|--c15t-overlay|string \|undefined|\`colors.overlay\` (default: \`hsla(0, 0%, 0%, 0.5)\`)|-|Optional|
+|--c15t-switch-track|string \|undefined|\`colors.switchTrack\` (default: \`hsl(0, 0%, 85%)\`)|-|Optional|
+|--c15t-switch-track-active|string \|undefined|\`colors.switchTrackActive\` (default: \`hsl(228, 100%, 60%)\`)|-|Optional|
+|--c15t-switch-thumb|string \|undefined|\`colors.switchThumb\` (default: \`hsl(0, 0%, 100%)\`)|-|Optional|
+|--c15t-font-family|string \|undefined|\`typography.fontFamily\` (default: \`system-ui, -apple-system, sans-serif\`)|-|Optional|
+|--c15t-font-size-sm|string \|undefined|\`typography.fontSize.sm\` (default: \`0.875rem\`)|-|Optional|
+|--c15t-font-size-base|string \|undefined|\`typography.fontSize.base\` (default: \`1rem\`)|-|Optional|
+|--c15t-font-size-lg|string \|undefined|\`typography.fontSize.lg\` (default: \`1.125rem\`)|-|Optional|
+|--c15t-font-weight-normal|string \|undefined|\`typography.fontWeight.normal\` (default: \`400\`)|-|Optional|
+|--c15t-font-weight-medium|string \|undefined|\`typography.fontWeight.medium\` (default: \`500\`)|-|Optional|
+|--c15t-font-weight-semibold|string \|undefined|\`typography.fontWeight.semibold\` (default: \`600\`)|-|Optional|
+|--c15t-line-height-tight|string \|undefined|\`typography.lineHeight.tight\` (default: \`1.25\`)|-|Optional|
+|--c15t-line-height-normal|string \|undefined|\`typography.lineHeight.normal\` (default: \`1.5\`)|-|Optional|
+|--c15t-line-height-relaxed|string \|undefined|\`typography.lineHeight.relaxed\` (default: \`1.75\`)|-|Optional|
+|--c15t-space-xs|string \|undefined|\`spacing.xs\` (default: \`0.25rem\`)|-|Optional|
+|--c15t-space-sm|string \|undefined|\`spacing.sm\` (default: \`0.5rem\`)|-|Optional|
+|--c15t-space-md|string \|undefined|\`spacing.md\` (default: \`1rem\`)|-|Optional|
+|--c15t-space-lg|string \|undefined|\`spacing.lg\` (default: \`1.5rem\`)|-|Optional|
+|--c15t-space-xl|string \|undefined|\`spacing.xl\` (default: \`2rem\`)|-|Optional|
+|--c15t-radius-sm|string \|undefined|\`radius.sm\` (default: \`0.25rem\`)|-|Optional|
+|--c15t-radius-md|string \|undefined|\`radius.md\` (default: \`0.5rem\`)|-|Optional|
+|--c15t-radius-lg|string \|undefined|\`radius.lg\` (default: \`0.75rem\`)|-|Optional|
+|--c15t-radius-full|string \|undefined|\`radius.full\` (default: \`9999px\`)|-|Optional|
+|--c15t-shadow-sm|string \|undefined|\`shadows.sm\` (default: \`0 1px 2px hsla(0, 0%, 0%, 0.05)\`)|-|Optional|
+|--c15t-shadow-md|string \|undefined|\`shadows.md\` (default: \`0 4px 12px hsla(0, 0%, 0%, 0.08)\`)|-|Optional|
+|--c15t-shadow-lg|string \|undefined|\`shadows.lg\` (default: \`0 8px 24px hsla(0, 0%, 0%, 0.12)\`)|-|Optional|
+|--c15t-duration-fast|string \|undefined|\`motion.duration.fast\` (default: \`100ms\`)|-|Optional|
+|--c15t-duration-normal|string \|undefined|\`motion.duration.normal\` (default: \`200ms\`)|-|Optional|
+|--c15t-duration-slow|string \|undefined|\`motion.duration.slow\` (default: \`300ms\`)|-|Optional|
+|--c15t-easing|string \|undefined|\`motion.easing\` (default: \`cubic-bezier(0.4, 0, 0.2, 1)\`)|-|Optional|
+|--c15t-easing-out|string \|undefined|\`motion.easingOut\` (default: \`cubic-bezier(0.215, 0.61, 0.355, 1)\`)|-|Optional|
+|--c15t-easing-in-out|string \|undefined|\`motion.easingInOut\` (default: \`cubic-bezier(0.645, 0.045, 0.355, 1)\`)|-|Optional|
+|--c15t-easing-spring|string \|undefined|\`motion.easingSpring\` (default: \`cubic-bezier(0.34, 1.56, 0.64, 1)\`)|-|Optional|
+
+## Overriding Variables
+
+Override in your stylesheet:
+
+```css
+:root {
+  --c15t-primary: #8b5cf6;
+  --c15t-surface: #fafafa;
+  --c15t-radius-md: 1rem;
+}
+
+/* Dark mode overrides */
+.dark,
+.c15t-dark {
+  --c15t-primary: #a78bfa;
+  --c15t-surface: #18181b;
+  --c15t-text: #fafafa;
+}
+```
+
+## Scoped Overrides
+
+Target specific components by scoping variables:
+
+```tsx
+<div className="checkout-consent">
+  <ConsentBanner />
+</div>
+```
+
+```css
+/* Only affect c15t components inside .checkout-consent */
+.checkout-consent {
+  --c15t-surface: #f0f9ff;
+  --c15t-radius-lg: 1.5rem;
+}
+```

package/docs/styling/overview.md

@@ -0,0 +1,459 @@
+---
+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, 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
+
+Use the `Theme` type for TypeScript autocomplete and validation:
+
+```tsx
+import { type ReactNode } from 'react';
+import { type Theme, ConsentManagerProvider } from '@c15t/react';
+
+const theme = {
+  colors: {
+    primary: '#6366f1',
+    primaryHover: '#4f46e5',
+    surface: '#ffffff',
+    text: '#1f2937',
+    textMuted: '#6b7280',
+  },
+  radius: {
+    md: '0.75rem',
+    lg: '1rem',
+  },
+  spacing: {
+    md: '1.25rem',
+  },
+} satisfies Theme;
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        theme,
+      }}
+    >
+      {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
+
+### Theme
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|colors|ColorTokens \|undefined|Color palette for light mode.|-|Optional|
+|dark|ColorTokens \|undefined|Dark mode color overrides.|-|Optional|
+|typography|TypographyTokens \|undefined|Typography settings for text elements.|-|Optional|
+|spacing|SpacingTokens \|undefined|Spacing scale for internal padding and margins.|-|Optional|
+|radius|RadiusTokens \|undefined|Border radius scale for rounded corners.|-|Optional|
+|shadows|ShadowTokens \|undefined|Box shadow scale for depth and elevation.|-|Optional|
+|motion|MotionTokens \|undefined|Animation and transition timing.|-|Optional|
+|consentActions|Object \|undefined|Semantic button styling for consent actions.|-|Optional|
+|slots|ComponentSlots \|undefined|Component-specific style overrides.|-|Optional|
+
+#### `colors` ColorTokens
+
+Color palette for light mode.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|primary|string \|undefined|Primary brand/accent color for interactive elements.|-|Optional|
+|primaryHover|string \|undefined|Hover/active state for primary elements.|-|Optional|
+|surface|string \|undefined|Main background color for panels and containers.|-|Optional|
+|surfaceHover|string \|undefined|Hover state for surface elements.|-|Optional|
+|border|string \|undefined|Border color for containers and inputs.|-|Optional|
+|borderHover|string \|undefined|Hover state for bordered elements.|-|Optional|
+|text|string \|undefined|Primary text color for headings and body.|-|Optional|
+|textMuted|string \|undefined|Muted text color for secondary content.|-|Optional|
+|textOnPrimary|string \|undefined|Text color for content on primary background. Auto-derived from \`primary\` when omitted.|-|Optional|
+|overlay|string \|undefined|Overlay color for modal backdrops.|-|Optional|
+|switchTrack|string \|undefined|Toggle track color (off state).|-|Optional|
+|switchTrackActive|string \|undefined|Toggle track color (on state).|-|Optional|
+|switchThumb|string \|undefined|Toggle thumb color.|-|Optional|
+
+#### `dark` ColorTokens
+
+Dark mode color overrides.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|primary|string \|undefined|Primary brand/accent color for interactive elements.|-|Optional|
+|primaryHover|string \|undefined|Hover/active state for primary elements.|-|Optional|
+|surface|string \|undefined|Main background color for panels and containers.|-|Optional|
+|surfaceHover|string \|undefined|Hover state for surface elements.|-|Optional|
+|border|string \|undefined|Border color for containers and inputs.|-|Optional|
+|borderHover|string \|undefined|Hover state for bordered elements.|-|Optional|
+|text|string \|undefined|Primary text color for headings and body.|-|Optional|
+|textMuted|string \|undefined|Muted text color for secondary content.|-|Optional|
+|textOnPrimary|string \|undefined|Text color for content on primary background. Auto-derived from \`primary\` when omitted.|-|Optional|
+|overlay|string \|undefined|Overlay color for modal backdrops.|-|Optional|
+|switchTrack|string \|undefined|Toggle track color (off state).|-|Optional|
+|switchTrackActive|string \|undefined|Toggle track color (on state).|-|Optional|
+|switchThumb|string \|undefined|Toggle thumb color.|-|Optional|
+
+#### `typography` TypographyTokens
+
+Typography settings for text elements.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|fontFamily|string \|undefined|Font family for all components.|-|Optional|
+|fontSize|Object \|undefined|Font sizes for text hierarchy.|-|Optional|
+|fontWeight|Object \|undefined|Font weights for emphasis.|-|Optional|
+|lineHeight|Object \|undefined|Line heights for readability.|-|Optional|
+
+#### `spacing` SpacingTokens
+
+Spacing scale for internal padding and margins.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|xs|string \|undefined|@default '0.25rem' (4px)|-|Optional|
+|sm|string \|undefined|@default '0.5rem' (8px)|-|Optional|
+|md|string \|undefined|@default '1rem' (16px)|-|Optional|
+|lg|string \|undefined|@default '1.5rem' (24px)|-|Optional|
+|xl|string \|undefined|@default '2rem' (32px)|-|Optional|
+
+#### `radius` RadiusTokens
+
+Border radius scale for rounded corners.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|sm|string \|undefined|@default '0.25rem' (4px)|-|Optional|
+|md|string \|undefined|@default '0.5rem' (8px)|-|Optional|
+|lg|string \|undefined|@default '0.75rem' (12px)|-|Optional|
+|full|string \|undefined|@default '9999px'|-|Optional|
+
+#### `shadows` ShadowTokens
+
+Box shadow scale for depth and elevation.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|sm|string \|undefined|@default '0 1px 2px hsla(0, 0%, 0%, 0.05)'|-|Optional|
+|md|string \|undefined|@default '0 4px 12px hsla(0, 0%, 0%, 0.08)'|-|Optional|
+|lg|string \|undefined|@default '0 8px 24px hsla(0, 0%, 0%, 0.12)'|-|Optional|
+
+#### `motion` MotionTokens
+
+Animation and transition timing.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|duration|Object \|undefined|Duration presets for transitions.|-|Optional|
+|easing|string \|undefined|Default CSS easing function for general animation curves.|-|Optional|
+|easingOut|string \|undefined|CSS easing function for enter/exit animations. Use for modals, tooltips, dropdowns, and any element entering or exiting.|-|Optional|
+|easingInOut|string \|undefined|CSS easing function for on-screen movement. Use when elements already on screen need to move or morph.|-|Optional|
+|easingSpring|string \|undefined|CSS easing function with spring-like overshoot. Use for playful, bouncy animations.|-|Optional|
+
+#### `consentActions`
+
+Semantic button styling for consent actions.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|default|ConsentActionStyle \|undefined|-|-|Optional|
+|accept|ConsentActionStyle \|undefined|-|-|Optional|
+|reject|ConsentActionStyle \|undefined|-|-|Optional|
+|customize|ConsentActionStyle \|undefined|-|-|Optional|
+
+#### `slots` ComponentSlots
+
+Component-specific style overrides.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|consentBanner|SlotStyle \|undefined|Root wrapper for the consent banner portal content.|-|Optional|
+|consentBannerCard|SlotStyle \|undefined|Main card container for banner content and actions.|-|Optional|
+|consentBannerHeader|SlotStyle \|undefined|Header region containing title and description.|-|Optional|
+|consentBannerTitle|SlotStyle \|undefined|Banner title text element.|-|Optional|
+|consentBannerDescription|SlotStyle \|undefined|Banner description text element.|-|Optional|
+|consentBannerFooter|SlotStyle \|undefined|Footer container for banner action buttons.|-|Optional|
+|consentBannerFooterSubGroup|SlotStyle \|undefined|Nested button group inside the banner footer.|-|Optional|
+|consentBannerTag|SlotStyle \|undefined|Branding tag rendered above the consent banner card.|-|Optional|
+|consentBannerOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the banner when enabled.|-|Optional|
+|consentDialog|SlotStyle \|undefined|Root wrapper for the consent dialog modal.|-|Optional|
+|consentDialogCard|SlotStyle \|undefined|Main dialog card container.|-|Optional|
+|consentDialogHeader|SlotStyle \|undefined|Dialog header region containing title and description.|-|Optional|
+|consentDialogTitle|SlotStyle \|undefined|Dialog title text element.|-|Optional|
+|consentDialogDescription|SlotStyle \|undefined|Dialog description text element.|-|Optional|
+|consentDialogContent|SlotStyle \|undefined|Dialog content region (typically holds ConsentWidget).|-|Optional|
+|consentDialogFooter|SlotStyle \|undefined|Footer container used by compound dialog layouts.|-|Optional|
+|consentDialogTag|SlotStyle \|undefined|Branding tag rendered below the stock consent dialog card.|-|Optional|
+|consentDialogOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the dialog.|-|Optional|
+|consentWidget|SlotStyle \|undefined|Root wrapper for the consent widget/preferences panel.|-|Optional|
+|consentWidgetAccordion|SlotStyle \|undefined|Accordion region listing consent categories.|-|Optional|
+|consentWidgetFooter|SlotStyle \|undefined|Footer area for widget actions and links.|-|Optional|
+|consentWidgetTag|SlotStyle \|undefined|Branding tag rendered below the standalone consent widget.|-|Optional|
+|frame|SlotStyle \|undefined|Frame wrapper used by blocking placeholders (e.g., iframe blocking).|-|Optional|
+|iabConsentBanner|SlotStyle \|undefined|Root wrapper for the IAB consent banner.|-|Optional|
+|iabConsentBannerCard|SlotStyle \|undefined|Main card container for IAB banner content.|-|Optional|
+|iabConsentBannerHeader|SlotStyle \|undefined|Header region for IAB banner title/description.|-|Optional|
+|iabConsentBannerFooter|SlotStyle \|undefined|Footer container for IAB banner actions.|-|Optional|
+|iabConsentBannerTag|SlotStyle \|undefined|Branding tag rendered above the IAB banner card.|-|Optional|
+|iabConsentBannerOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the IAB banner.|-|Optional|
+|iabConsentDialog|SlotStyle \|undefined|Root wrapper for the IAB consent dialog.|-|Optional|
+|iabConsentDialogCard|SlotStyle \|undefined|Main card container for IAB dialog content.|-|Optional|
+|iabConsentDialogHeader|SlotStyle \|undefined|Header region for IAB dialog title/description.|-|Optional|
+|iabConsentDialogFooter|SlotStyle \|undefined|Footer container for IAB dialog actions.|-|Optional|
+|iabConsentDialogTag|SlotStyle \|undefined|Branding tag rendered below the IAB dialog card.|-|Optional|
+|iabConsentDialogOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the IAB dialog.|-|Optional|
+|buttonPrimary|SlotStyle \|undefined|Shared primary button style used across consent components.|-|Optional|
+|buttonSecondary|SlotStyle \|undefined|Shared secondary button style used across consent components.|-|Optional|
+|toggle|SlotStyle \|undefined|Shared toggle/switch style used for category controls.|-|Optional|

package/docs/styling/slots.md

@@ -0,0 +1,127 @@
+---
+title: Component Slots
+description: Target individual component parts with styles using the slot system - className strings or inline style objects.
+---
+## 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
+
+### ComponentSlots
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|consentBanner|SlotStyle \|undefined|Root wrapper for the consent banner portal content.|-|Optional|
+|consentBannerCard|SlotStyle \|undefined|Main card container for banner content and actions.|-|Optional|
+|consentBannerHeader|SlotStyle \|undefined|Header region containing title and description.|-|Optional|
+|consentBannerTitle|SlotStyle \|undefined|Banner title text element.|-|Optional|
+|consentBannerDescription|SlotStyle \|undefined|Banner description text element.|-|Optional|
+|consentBannerFooter|SlotStyle \|undefined|Footer container for banner action buttons.|-|Optional|
+|consentBannerFooterSubGroup|SlotStyle \|undefined|Nested button group inside the banner footer.|-|Optional|
+|consentBannerTag|SlotStyle \|undefined|Branding tag rendered above the consent banner card.|-|Optional|
+|consentBannerOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the banner when enabled.|-|Optional|
+|consentDialog|SlotStyle \|undefined|Root wrapper for the consent dialog modal.|-|Optional|
+|consentDialogCard|SlotStyle \|undefined|Main dialog card container.|-|Optional|
+|consentDialogHeader|SlotStyle \|undefined|Dialog header region containing title and description.|-|Optional|
+|consentDialogTitle|SlotStyle \|undefined|Dialog title text element.|-|Optional|
+|consentDialogDescription|SlotStyle \|undefined|Dialog description text element.|-|Optional|
+|consentDialogContent|SlotStyle \|undefined|Dialog content region (typically holds ConsentWidget).|-|Optional|
+|consentDialogFooter|SlotStyle \|undefined|Footer container used by compound dialog layouts.|-|Optional|
+|consentDialogTag|SlotStyle \|undefined|Branding tag rendered below the stock consent dialog card.|-|Optional|
+|consentDialogOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the dialog.|-|Optional|
+|consentWidget|SlotStyle \|undefined|Root wrapper for the consent widget/preferences panel.|-|Optional|
+|consentWidgetAccordion|SlotStyle \|undefined|Accordion region listing consent categories.|-|Optional|
+|consentWidgetFooter|SlotStyle \|undefined|Footer area for widget actions and links.|-|Optional|
+|consentWidgetTag|SlotStyle \|undefined|Branding tag rendered below the standalone consent widget.|-|Optional|
+|frame|SlotStyle \|undefined|Frame wrapper used by blocking placeholders (e.g., iframe blocking).|-|Optional|
+|iabConsentBanner|SlotStyle \|undefined|Root wrapper for the IAB consent banner.|-|Optional|
+|iabConsentBannerCard|SlotStyle \|undefined|Main card container for IAB banner content.|-|Optional|
+|iabConsentBannerHeader|SlotStyle \|undefined|Header region for IAB banner title/description.|-|Optional|
+|iabConsentBannerFooter|SlotStyle \|undefined|Footer container for IAB banner actions.|-|Optional|
+|iabConsentBannerTag|SlotStyle \|undefined|Branding tag rendered above the IAB banner card.|-|Optional|
+|iabConsentBannerOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the IAB banner.|-|Optional|
+|iabConsentDialog|SlotStyle \|undefined|Root wrapper for the IAB consent dialog.|-|Optional|
+|iabConsentDialogCard|SlotStyle \|undefined|Main card container for IAB dialog content.|-|Optional|
+|iabConsentDialogHeader|SlotStyle \|undefined|Header region for IAB dialog title/description.|-|Optional|
+|iabConsentDialogFooter|SlotStyle \|undefined|Footer container for IAB dialog actions.|-|Optional|
+|iabConsentDialogTag|SlotStyle \|undefined|Branding tag rendered below the IAB dialog card.|-|Optional|
+|iabConsentDialogOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the IAB dialog.|-|Optional|
+|buttonPrimary|SlotStyle \|undefined|Shared primary button style used across consent components.|-|Optional|
+|buttonSecondary|SlotStyle \|undefined|Shared secondary button style used across consent components.|-|Optional|
+|toggle|SlotStyle \|undefined|Shared toggle/switch style used for category controls.|-|Optional|
+
+### SlotStyle
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|SlotStyle|SlotStyle|Type alias for SlotStyle|-|✅ Required|