@c15t/nextjs 2.2.0 → 3.0.0-alpha.0

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

@@ -1,299 +1,215 @@
 ---
-title: Styling Overview
-description: Five approaches for theming consent components — design tokens,
-  component slots, CSS variables, className, and noStyle mode.
+title: Styling
+description: Import the Next.js stylesheet and theme c15t components with
+  tokens, slots, and class names through ConsentRoot options.
 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:
+## Stylesheet
 
-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
+Import c15t once from the global stylesheet loaded by `app/layout.tsx` in the
+App Router or `pages/_app.tsx` in the Pages Router. With Tailwind CSS 4, place
+it after the Tailwind import so the component layers keep their order:
 
-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>
-  );
-}
+```css
+@import 'tailwindcss';
+@import 'c15t/next/styles.css';
 ```
 
-## Styling Inside Pre-Built Components
-
-Start here before you consider compound components or headless mode.
+Without Tailwind, omit its import. Keep the existing global CSS import in the
+layout or `_app.tsx`. Tailwind CSS 3 uses the separate build shown below.
 
-### 1. Provider and component configuration
+Every rule lives in `@layer components`, so unlayered utilities from Tailwind
+v4 and atomic classes from StyleX override it without specificity tricks.
+Tailwind v3 treats `@layer components` as its own directive, so import the
+Tailwind 3 build from your Tailwind entry instead, between the `components`
+and `utilities` directives:
 
-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" />
+```css
+@tailwind base;
+@tailwind components;
+@import 'c15t/next/styles.tw3.css';
+@tailwind utilities;
 ```
 
-### 2. Design tokens
+## Tokens
 
-Set global values for colors, typography, spacing, radius, shadows, and motion:
+The provider snippets below are partial configuration examples. Apply them in
+your existing Client Component wrapper, keeping its transport, prefetch,
+children and other options. `ConsentRoot` also accepts `theme` and
+`components` through `options`.
 
-```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:
+Colors, radii, shadows, typography, and motion come from `--c15t-*` custom
+properties. Set them on the provider through `theme`, or override the
+variables directly in your CSS.
 
 ```tsx
-options={{
-  theme: {
-    slots: {
-      consentBannerCard: 'rounded-[28px] shadow-xl',
-      consentBannerFooter: 'border-t border-black/10',
-      consentBannerTitle: 'tracking-tight',
-    },
-  },
-}}
+import { ConsentProvider, defineTheme } from 'c15t/next';
+
+const theme = defineTheme({
+	colors: { primary: '#2f6f4e' },
+	radius: { lg: '4px' },
+	consentActions: {
+		primary: { variant: 'primary', mode: 'filled' },
+		dismiss: { variant: 'neutral', mode: 'stroke' },
+	},
+});
+
+<ConsentProvider options={{ mode, theme }} />;
 ```
 
-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.
+`consentActions` decides how each action role looks: `default` applies to
+every button, `primary` to whichever actions the policy or your props mark
+primary, and `accept`, `reject`, `customize`, and `dismiss` to one role each.
+Per-action keys win over `primary`, which wins over `default`.
 
-Reach for this after tokens and slots, not before.
+Banner sizing has its own variables. Override them in CSS when a variant
+needs a different footprint:
 
-```tsx
-options={{
-  theme: {
-    slots: {
-      consentBannerFooter: 'bg-[var(--banner-footer)]',
-    },
-  },
-}}
-```
+| Variable                            | Default | Applies to       |
+| ----------------------------------- | ------- | ---------------- |
+| `--consent-banner-max-width`        | `440px` | `floating` cards |
+| `--consent-banner-widget-max-width` | `20rem` | `widget` chips   |
+| `--consent-banner-wall-max-width`   | `30rem` | `wall` cards     |
 
-## Escalating Beyond Pre-Built Components
+## Colors by consent model
 
-Only move up this ladder when the lower rung cannot satisfy the request.
+The primary action can change while the brand color stays the same. Set
+`consentActions.primary` once, then select `primaryButton` per policy as
+shown in [ConsentBanner](../components/consent-banner.md#per-policy-buttons).
 
-### 5. Compound components
+To give opt-in and opt-out banners different colors, scope the tokens to
+the root's attributes. Include hover and foreground colors when overriding
+CSS tokens directly:
 
-Use compound components when you need to rearrange existing c15t primitives:
+```css
+[data-prompt][data-model='opt-in'] {
+	--c15t-primary: #2f6f4e;
+	--c15t-primary-hover: #24563c;
+	--c15t-text-on-primary: #fff;
+}
 
-```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>
+[data-prompt][data-model='opt-out'] {
+	--c15t-primary: #6b3fa0;
+	--c15t-primary-hover: #55327f;
+	--c15t-text-on-primary: #fff;
+}
 ```
 
-### 6. `noStyle`
+These colors apply to the action marked primary. Button layout and color
+changes do not change the policy or expire a saved choice.
 
-Use `noStyle` only when the c15t structure is still correct but you want to replace all visual defaults:
+## Slots
 
-```tsx
-<ConsentBanner noStyle />
-```
+Each component part is a slot. A slot accepts any attributes the element
+takes, so the contract is the same whether you write class strings or pass an
+object with `className` and `style`. Set slots on the provider under
+`components`, keyed by component and part.
 
-### 7. Headless
+For a full-width notice, use the supported `bar` variant. In a Client Component
+inside the existing boundary, replace the stock banner with:
 
-Go headless only when you are replacing both markup and behavior. For that path, continue to [Headless Mode](../headless).
+```tsx title="components/regional-banner.tsx"
+'use client';
 
-## Common Styling Tasks
+import { ConsentBanner, usePolicyRule } from 'c15t/next';
 
-### Change the banner footer background
-
-```tsx
-options={{
-  theme: {
-    colors: {
-      surfaceHover: '#f6f3ee',
-    },
-  },
-}}
+export function RegionalBanner() {
+  const policy = usePolicyRule();
+  return <ConsentBanner variant={policy?.prompt === 'notice' ? 'bar' : 'floating'} />;
+}
 ```
 
-Use `theme.colors.surfaceHover` before trying raw CSS.
+To remove the notice card's radius, add these values to the existing
+`options.components.banner` slots. The root owns `data-prompt`, so the card
+uses Tailwind's `group` selector to read it:
 
-### Change the banner card background
-
-```tsx
-options={{
-  theme: {
-    colors: {
-      surface: '#fffdf8',
-    },
+```ts
+const bannerSlots = {
+  root: { className: 'group' },
+  card: { className: 'group-data-[prompt=notice]:rounded-none' },
+  rightLink: {
+    className: 'underline-offset-4 data-[right=opt-out]:text-red-700',
   },
-}}
-```
+};
 
-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',
-    },
-  },
-}}
+// In the existing options.components object:
+// banner: bannerSlots
 ```
 
-### Change stock consent action button styles semantically
+The root also carries `data-variant`, so you can restyle one shape without
+touching the others. Tailwind, giving a `bar` a brand-colored top edge and
+tighter text:
 
 ```tsx
-options={{
-  theme: {
-    consentActions: {
-      default: { mode: 'stroke' },
-      accept: { variant: 'primary', mode: 'stroke' },
-      customize: { variant: 'neutral', mode: 'ghost' },
-    },
-  },
-}}
+<ConsentProvider
+	options={{
+		mode,
+		presentation: { prompt: { variant: 'bar' } },
+		components: {
+			banner: {
+				root: { className: 'group' },
+				card: {
+					className:
+						'group-data-[variant=bar]:border-t-4 group-data-[variant=bar]:border-t-emerald-600',
+				},
+			},
+			description: {
+				banner: { className: 'group-data-[variant=bar]:text-xs' },
+			},
+		},
+	}}
+/>
 ```
 
-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',
-        },
-      },
-    },
-  },
-}}
-```
+`data-variant` sits on the root, so child slots use Tailwind's `group`
+prefix to read it.
 
-### Enable dark mode safely
+StyleX, spreading the result of `stylex.props()` into a slot:
 
 ```tsx
-options={{
-  colorScheme: 'system',
-  theme: {
-    colors: { surface: '#ffffff', text: '#1f2937' },
-    dark: { surface: '#111827', text: '#f9fafb' },
-  },
-}}
+import * as stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+	card: { borderRadius: 0, boxShadow: 'none' },
+	rightLink: { textUnderlineOffset: 4, color: 'rgb(185 28 28)' },
+});
+
+<ConsentProvider
+	options={{
+		mode,
+		components: {
+			banner: {
+				card: stylex.props(styles.card),
+				rightLink: stylex.props(styles.rightLink),
+			},
+		},
+	}}
+/>;
 ```
 
-> ℹ️ **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.\*
+Set `noStyle` on a component to drop the built-in classes from every part and
+keep only what your slots pass. Set `noStyle` in the provider options to do it
+for every component.
+
+Banner slot keys under `components.banner`:
+
+| Key           | Element                                                                                                           |
+| ------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `root`        | Fixed-position wrapper carrying `data-prompt`, `data-model`, `data-variant`, `data-position`, and `data-blocking` |
+| `cardShell`   | Sizes the card and holds the branding tag                                                                         |
+| `card`        | The visible card, carrying `data-state`                                                                           |
+| `header`      | Title and description container                                                                                   |
+| `title`       | Heading                                                                                                           |
+| `footer`      | Action area                                                                                                       |
+| `actions`     | Group of action groups                                                                                            |
+| `actionGroup` | One group of equally prominent actions                                                                            |
+| `rights`      | Group of right links, rendered before the actions                                                                 |
+| `rightLink`   | One right link, carrying `data-action="right"` and `data-right`                                                   |
+| `overlay`     | Backdrop shown when the banner blocks the page                                                                    |
+
+Action buttons carry `data-action` and `data-variant`, and right links carry
+`data-action="right"`, so a single rule such as `[data-action='dismiss']` or
+`[data-action='right']` styles one role across every surface. Right links are
+underlined text by default, so the only button on a notice is the primary
+action.