{/* This file is NOT rendered directly. Sections are imported by framework pages. */}

<section id="intro">
  Building custom consent UI is easier now because c15t exposes multiple layers of policy-aware primitives instead of forcing you to reconstruct banner rules by hand.

  Think of customization as a ladder:

  * stock component props for the shortest path
  * `ConsentBanner.PolicyActions` and `ConsentWidget.PolicyActions` when you want custom structure but still want c15t to resolve policy-aware actions
  * `useHeadlessConsentUI()` when you need fully manual action rendering, custom controls, or non-standard flow

  > ⚠️ **Warning:**
  > Headless is the last step in the customization ladder. Use this guide only when pre-built components, tokens, slots, compound components, and noStyle are no longer sufficient.

  The headless stack underneath that is:

  * `useHeadlessConsentUI()` for policy-aware banner/dialog actions, ordering, layout, and primary actions hints
  * `@c15t/ui/utils` for the pure policy-action helpers that framework packages build on
  * `useConsentManager()` for runtime state, categories, selected consent state, and policy metadata
  * `useTranslations()` for the resolved copy
  * `offlinePolicy.policyPacks` for offline previews that behave like backend policy resolution

  The split is intentional: `@c15t/ui` owns pure policy-action resolution, while the framework hooks own visibility, consent mutations, and reactive state.

  > ℹ️ **Info:**
  > This guide is about building your own components while still respecting resolved policy-pack behavior. For the general headless overview, see Headless Mode.
</section>

<section id="choose-layer">
  ## Choose the Smallest Layer That Solves the Job

  Start with the smallest API surface that still gives you the behavior you need:

  * Stay with stock components when you only need theming, spacing, copy, or legal-link changes
  * Use `ConsentBanner.PolicyActions` or `ConsentWidget.PolicyActions` when you want a custom compound-component layout but still want grouped actions, ordering, and primary emphasis to come from policy
  * Add `renderAction` when the grouping is still correct but you want to remap actions to stock c15t button compounds
  * Reach for `useHeadlessConsentUI()` only when you need custom button elements, need to map `actionGroups` yourself, wire non-button controls, or coordinate the consent UI with a more custom state machine

  This order matters because every step down the ladder gives you more control, but also makes it easier for your UI to drift away from the resolved policy if you stop using the provided state.
</section>

<section id="before-you-build">
  ## Before You Build Headless UI

  Do not use headless mode for problems that are still inside the stock component model:

  * Use `layout`, `direction`, `primaryButton`, and `legalLinks` before you rebuild banner markup
  * Use `theme.consentActions` before you swap out stock actions
  * Use tokens such as `colors.surface` and `colors.surfaceHover` before raw CSS overrides
  * Use slots such as `consentBannerCard`, `consentBannerFooter`, and `consentDialogCard` before compound components
  * Use `ConsentManagerProvider.options.i18n` before rebuilding UI just to change text

  A good rule: if the stock banner or dialog structure is still correct, you probably do not need headless mode.
</section>

<section id="what-you-get">
  ## What the Headless Tooling Gives You

  The main win is that your custom UI can stay aligned with policy packs without duplicating policy logic in your components.

  `useHeadlessConsentUI()` already resolves:

  * which actions are allowed
  * the order those actions should render in
  * grouped actions from policy `layout`
  * layout `direction` (`row` or `column`)
  * the primary actions
  * UI profile and scroll-lock hints
  * whether the banner or dialog should currently be visible

  The hook also gives you the policy-aware action helpers you are expected to call:

  * `performBannerAction('accept' | 'reject')`
  * `performDialogAction('accept' | 'reject')`
  * `saveCustomPreferences()` for the dialog `customize` action
  * `openDialog()`, `openBanner()`, and `closeUI()` for surface visibility

  That means your component mostly focuses on markup and design-system concerns instead of re-implementing policy interpretation.

  For most compound-component layouts, start with `ConsentBanner.PolicyActions` or `ConsentWidget.PolicyActions`. They render stock c15t buttons and translations by default, and `renderAction` is only needed when you want to override which stock compound renders for each action. Reach for manual `actionGroups` mapping when you need action rendering that no longer fits the stock button compounds.
</section>

<section id="not-for-styling">
  ## What Headless Is Not For

  Headless mode is not the recommended path for:

  * changing the banner footer background
  * rounding the stock banner card
  * restyling stock banner or dialog buttons
  * changing consent copy

  Those should stay in the pre-built stack with tokens, slots, `theme.consentActions`, and provider `i18n`.
</section>

<section id="checklist">
  ## What a Policy-Aware Headless Component Should Respect

  When you build custom banner or dialog components, make sure they use:

  * `activeUI` or `banner.isVisible` / `dialog.isVisible` for visibility
  * `allowedActions`, `actionGroups`, and `primaryActions` instead of hard-coding buttons
  * `primaryActions` for visual emphasis
  * `consentCategories` when deciding which category toggles to render
  * `policyDecision` when you want to debug why a specific UI state was chosen

  If you ignore those values, your custom UI can drift away from the resolved policy pack even though the underlying consent engine is configured correctly.
</section>

<section id="validation">
  ## Validation and Testing

  If you are building a reusable headless component library, validate your rendered UI against the resolved runtime policy in tests.

  The core package exposes:

  * `getEffectivePolicy(initData)` to read the resolved policy from `/init`
  * `validateUIAgainstPolicy({ policy, state })` to detect mismatches such as wrong actions, layout, or mode

  This is useful when your design system renders custom button arrangements and you want tests to catch policy drift early.
</section>