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

package/docs/integrations/posthog.md

@@ -1,7 +1,7 @@
 ---
 title: PostHog
 description: PostHog is an open-source product analytics platform for tracking user behavior, session replays, feature flags, and A/B testing. It supports cookieless tracking, allowing analytics to continue even without cookie consent.
-lastModified: 2025-09-19
+lastModified: 2026-04-08
 
 icon: posthog
 ---
@@ -25,7 +25,7 @@ This is the recommended approach if you're using the Posthog JS SDK, this is com
    posthog.opt_out_capturing() // Avoids accidental tracking without consent till c15t has loaded
    ```
 
-2. **Adding the SDK callback to c15t** The PostHog SDK approach uses callbacks.onConsentSet instead of scripts. This lets you toggle PostHog's opt-in/opt-out based on the user's consent choice.
+2. **Sync settled consent once, then subscribe to real changes** The recommended PostHog SDK approach uses two phases: run one initial sync after c15t has finished resolving consent, then subscribe to future real preference changes with subscribeToConsentChanges().
 
    > ℹ️ Info:
    >
@@ -35,20 +35,38 @@ This is the recommended approach if you're using the Posthog JS SDK, this is com
    import { getOrCreateConsentRuntime } from 'c15t';
    import { posthog } from 'posthog-js';
 
-   getOrCreateConsentRuntime({
+   function syncPostHogMeasurementConsent(hasMeasurementConsent: boolean) {
+     if (hasMeasurementConsent) {
+       posthog.opt_in_capturing();
+     } else {
+       posthog.opt_out_capturing();
+     }
+   }
+
+   const runtime = getOrCreateConsentRuntime({
      mode: 'hosted',
      callbacks: {
-       onConsentSet({ preferences }) {
-         if (preferences.measurement) {
-           posthog.opt_in_capturing();
-         } else {
-           posthog.opt_out_capturing();
-         }
-       }
-     }
+       onBannerFetched() {
+         syncPostHogMeasurementConsent(
+           runtime.consentStore.getState().has('measurement')
+         );
+       },
+     },
    });
+
+   runtime.consentStore
+     .getState()
+     .subscribeToConsentChanges(({ allowedCategories }) => {
+       syncPostHogMeasurementConsent(
+         allowedCategories.includes('measurement')
+       );
+     });
    ```
 
+   > ℹ️ Info:
+   >
+   > Avoid using onConsentSet plus manual deduplication for PostHog. subscribeToConsentChanges() already gives you the exact change-only semantics most analytics SDKs need.
+
 ## PostHog Script Implementation
 
 If you want to load posthog via a script tag it's recommended to use this approach.
@@ -80,8 +98,13 @@ By default c15t will always load the script regardless of consent. This is becau
    posthog({
      id: 'phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
      apiHost: 'https://eu.i.posthog.com',
-     defaults: '2025-05-24',
-     options: { person_profiles: 'identified_only' }
+     scriptUrl: 'https://eu-assets.i.posthog.com/static/array.js',
+     initOptions: {
+       api_host: 'https://eu.i.posthog.com',
+       ui_host: 'https://eu.i.posthog.com',
+       autocapture: false,
+       person_profiles: 'identified_only',
+     }
    })
    ```
 
@@ -92,10 +115,9 @@ By default c15t will always load the script regardless of consent. This is becau
 |Property|Type|Description|Default|Required|
 |:--|:--|:--|:--|:--:|
 |id|string|Your posthog id, begins with 'phc\_'.|-|✅ Required|
-|apiHost|string|Your posthog api host.|'https\://eu.i.posthog.com'|✅ Required|
-|defaults|string|The defaults for the posthog script.|-|✅ Required|
-|options|Record\<string, unknown>|Other optional options for the posthog script.|-|✅ Required|
-|script|Script \|undefined|Override or extend the default script values. Options: \`id\`: 'posthog-consent'; \`category\`: 'measurement'|-|Optional|
+|apiHost|string \|undefined|Your posthog api host.|'https\://eu.i.posthog.com'|Optional|
+|scriptUrl|string \|undefined|The PostHog array loader URL.|-|Optional|
+|initOptions|Record\<string, unknown> \|undefined|PostHog init options passed to \`posthog.init(...)\`.|-|Optional|
 
 ### Script
 

package/docs/integrations/tiktok-pixel.md

@@ -31,7 +31,7 @@ tiktokPixel({
 |Property|Type|Description|Default|Required|
 |:--|:--|:--|:--|:--:|
 |pixelId|string|Your TikTok Pixel ID|-|✅ Required|
-|script|Script \|undefined|Override or extend the default script values. Options: \`id\`: 'tiktok-pixel'; \`src\`: \`https\://analytics.tiktok.com/i18n/pixel/events.js\`; \`category\`: 'marketing'|-|Optional|
+|scriptSrc|string \|undefined|TikTok Pixel loader base URL.|-|Optional|
 
 ### Script
 

package/docs/integrations/x-pixel.md

@@ -37,7 +37,7 @@ xPixelEvent('tw-xxxx-xxxx', { value: 10.00, currency: 'USD' });
 |Property|Type|Description|Default|Required|
 |:--|:--|:--|:--|:--:|
 |pixelId|string|Your X Pixel ID|-|✅ Required|
-|script|Script \|undefined|Override or extend the default script values. Options: \`id\`: 'x-pixel'; \`src\`: \`https\://static.ads-twitter.com/uwt.js\`; \`category\`: 'marketing'|-|Optional|
+|scriptSrc|string \|undefined|X Pixel loader URL.|-|Optional|
 
 ### Script
 

package/docs/optimization.md

@@ -50,7 +50,7 @@ const prefetchScript = buildPrefetchScript({
 </head>
 ```
 
-Then consume the prefetched data in your provider:
+Then initialize your provider normally. Matching prefetched data is consumed automatically by the runtime during first store initialization:
 
 ```tsx
 import {
@@ -58,7 +58,6 @@ import {
   ConsentBanner,
   ConsentDialog,
 } from '@c15t/react';
-import { getPrefetchedInitialData } from 'c15t';
 
 export default function App({ children }: { children: React.ReactNode }) {
   return (
@@ -66,9 +65,6 @@ export default function App({ children }: { children: React.ReactNode }) {
       options={{
         mode: 'hosted',
         backendURL: '/api/c15t',
-        ssrData: getPrefetchedInitialData({
-          backendURL: '/api/c15t',
-        }),
       }}
     >
       <ConsentBanner />
@@ -80,7 +76,7 @@ export default function App({ children }: { children: React.ReactNode }) {
 ```
 
 > ℹ️ **Info:**
-> If you use overrides or custom credentials in buildPrefetchScript, pass the same values to getPrefetchedInitialData(...) so it resolves the matching prefetched request.
+> If overrides.gpc conflicts with the browser's ambient GPC signal, the prefetched entry is not reused and c15t falls back to a normal client /init.
 
 ## Keep The Provider Mounted Across Navigation
 

package/docs/policy-packs.md

@@ -6,7 +6,7 @@ Policy packs configure how c15t handles regional consent — which model (opt-in
 
 **For most apps, you just need a `ConsentManagerProvider` pointing at your backend with presets configured there.** The frontend receives the resolved policy via the `/init` response — no client-side policy config required.
 
-When a backend isn't available — local development, static previews, Storybook, or as a resilience fallback — you can pass policies directly to the provider via `offlinePolicy.policyPacks` and c15t resolves them locally.
+When a backend isn't available — local development, static previews, Storybook, automated tests, or as a resilience fallback during a temporary outage — you can pass policies directly to the provider via `offlinePolicy.policyPacks` and c15t resolves them locally.
 
 > ℹ️ **Info:**
 > For QA and testing, use the c15t DevTools to simulate different regions and policy responses against your real backend, rather than switching to offline mode.
@@ -29,9 +29,9 @@ When using consent.io or a self-hosted backend, the provider connects automatica
 
 The backend resolves the correct policy based on the visitor's geo data and returns it in the `/init` response. Configure your presets on the backend side.
 
-## Offline Presets (Fallback)
+## Offline Presets (Development and Fallback)
 
-When no backend is available, pass presets directly to the provider:
+Use offline presets mainly for local development, Storybook, deterministic tests, or temporary backend outages:
 
 ```tsx
 import { policyPackPresets } from '@c15t/react';
@@ -105,7 +105,7 @@ export function ConsentManager({ children }: { children: ReactNode }) {
 
 ## Offline / Fallback
 
-For local development, static sites, or when the backend is unreachable, pass policies directly:
+For local development, previews, automated tests, or when the backend is temporarily unreachable, pass policies directly:
 
 ```tsx
 import type { ReactNode } from 'react';
@@ -144,7 +144,7 @@ export function ConsentManager({ children }: { children: ReactNode }) {
 ## Provider Shape
 
 Configure packs through `offlinePolicy.policyPacks`. Add `offlinePolicy.i18n`
-when you want offline mode to mirror hosted policy-profile language behavior:
+when you want local previews or fallback behavior to mirror hosted policy-profile language behavior:
 
 ```tsx
 <ConsentManagerProvider
@@ -203,7 +203,7 @@ With that setup, offline mode resolves language the same way as hosted mode:
 |`offlinePolicy: { policyPacks: [] }`|Explicit no-banner mode|
 |Non-empty pack, no match, no default|Explicit no-banner mode|
 
-Omitting the option gives you a safe opt-in default for local development and outage scenarios. Providing it tells c15t you want policy-driven behavior exactly as configured.
+Omitting the option gives you a safe opt-in default for local development and outage scenarios. Providing it tells c15t you want deterministic preview or fallback behavior exactly as configured.
 
 ## QA and Debugging
 
@@ -215,7 +215,7 @@ For deeper inspection:
 * Open the DevTools Policy panel to inspect matcher resolution and fingerprints
 * Compare your frontend preview with the backend `/init` response before shipping
 
-If you need fully deterministic resolution without a backend (e.g., in automated tests or Storybook), pair `offlinePolicy.policyPacks` with `overrides`:
+If you need fully deterministic resolution without a backend during testing or preview work (for example, in automated tests or Storybook), pair `offlinePolicy.policyPacks` with `overrides`:
 
 ```tsx
 options={{

package/docs/quickstart.md

@@ -33,15 +33,17 @@ availableIn:
    |yarn|`yarn add @c15t/react`|
    |bun|`bun add @c15t/react`|
 
-2. **Import styles** Import the prebuilt component stylesheet at the root of your application. This is required for styled components to render correctly.
+2. **Import styles** Import the prebuilt component stylesheet in your app-level CSS entrypoint. This is required for styled components to render correctly.
 
-   ```tsx
-   import '@c15t/react/styles.css';
+   ```css
+   @import "@c15t/react/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.
+
    > ℹ️ Info:
    >
-   > If you are using the headless API or fully custom styling, you can skip this import.
+   > If you are using the headless API or fully custom styling, you can skip this import. src/main.tsx should keep importing ./index.css as usual.
 
 3. **Create ConsentManager components** Create a provider component with the consent UI and a wrapper that re-exports it. This initializes the consent store and makes consent state available to all child components.
 
@@ -81,7 +83,11 @@ availableIn:
 
    > ℹ️ Info:
    >
-   > Don't have a backend yet? You can use mode: 'offline' for local-only consent storage, but review the browser-only storage consequences before choosing it for production.
+   > Hosted mode is the recommended production setup because the backend resolves jurisdiction and policy, keeps durable consent records, and lets c15t recover from temporary network failures by re-syncing later.
+   >
+   > ℹ️ Info:
+   >
+   > Don't have a backend yet? You can use mode: 'offline' for local-only consent storage, but it gives up backend audit history, server-side consent awareness, and automatic jurisdiction detection. Review the browser-only storage consequences before choosing it for production.
 
 4. **Mount ConsentManager at the app root** Wrap your existing app tree with ConsentManager so all routes/components can access consent state.
 

package/docs/script-loader.md

@@ -4,7 +4,7 @@ description: Gate third-party scripts behind consent - load Google Analytics, Me
 ---
 The script loader manages third-party scripts based on consent state. Scripts are defined in the provider's `scripts` option and are automatically loaded when their required consent category is granted, and unloaded when consent is revoked.
 
-c15t has a collection of premade scripts available on the @c15t/scripts package. It's recomended to check if a pre-built integration exists before manually creating a script, see the [integrations overview](/docs/integrations/overview).
+c15t has a collection of premade scripts available in `@c15t/scripts`. Check the [integrations overview](/docs/integrations/overview) first before manually building a script.
 
 |Package manager|Command|
 |:--|:--|
@@ -15,6 +15,12 @@ c15t has a collection of premade scripts available on the @c15t/scripts package.
 
 > ℹ️ **Info:**
 > We recommend using the pre-built integrations when possible.
+>
+> ℹ️ **Info:**
+> If you need a vendor we do not ship yet, see the custom integration guide. It covers both one-off Script objects and reusable manifest-backed integrations.
+>
+> ℹ️ **Info:**
+> For app-specific scripts, use a plain Script object. For reusable integrations, prefer a manifest-backed helper so startup phases, consent signaling, and future server-side loading support stay structured.
 
 ## Basic Usage
 
@@ -47,6 +53,21 @@ export function ConsentManager({ children }: { children: ReactNode }) {
 }
 ```
 
+## Choose the Right Approach
+
+* Use a plain `Script` for one-off app code.
+* Use a manifest-backed helper in `@c15t/scripts` for reusable integrations, contributions, or anything that needs structured startup behavior.
+
+If you are building something reusable, start with the [custom integration guide](/docs/integrations/building-integrations) before using raw callbacks.
+
+## Reusable Integrations
+
+For app-specific use, raw `Script` objects are usually enough.
+
+For reusable integrations, c15t uses a manifest-backed model in `@c15t/scripts`. That keeps startup phases, consent signaling, and vendor-specific boot logic structured instead of hidden inside large callback bodies.
+
+If you are building an integration for multiple apps or contributing upstream, use the [custom integration guide](/docs/integrations/building-integrations).
+
 ## Script Types
 
 ### Standard Scripts

package/docs/styling/classnames.md

@@ -2,15 +2,11 @@
 title: Class Names
 description: Style consent components using className props and per-slot className targeting via the theme.
 ---
-## Component className
+## Prefer Slots for Stock Components
 
-All consent components accept a `className` prop:
+There is no single top-level `className` contract across every pre-built consent component.
 
-```tsx
-<ConsentBanner className="my-banner" />
-<ConsentDialog className="my-dialog" />
-<ConsentWidget className="my-widget" />
-```
+For the stock `ConsentBanner`, `ConsentDialog`, and `ConsentWidget`, prefer `theme.slots` first. That keeps the markup intact and lets you target the exact part you need.
 
 ## Per-Slot className
 
@@ -59,9 +55,19 @@ const theme = {
 }
 ```
 
-## noStyle Mode
+## When to Use Raw className
+
+Use raw className-level styling when:
+
+* your styling system is already class-driven
+* tokens are too broad for the change
+* slots already identify the correct element
 
-Use `noStyle` when you want to remove defaults and style from scratch:
+If the request is "make the banner footer darker", prefer `theme.colors.surfaceHover` first. If the request is "add a border and spacing only to the footer", prefer `theme.slots.consentBannerFooter`.
+
+## Advanced: `noStyle`
+
+Use `noStyle` only when you want to remove defaults and style from scratch while still keeping c15t's component structure:
 
 ```tsx
 {/* Remove all styles from a specific component */}
@@ -81,4 +87,6 @@ const theme = {
 } satisfies Theme;
 ```
 
+Treat `noStyle` as an advanced escape hatch. Do not jump to it just because a token or slot needs debugging.
+
 For full custom markup and behavior, continue to [Headless Mode](../headless).

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