## Named themes

```js
lightning("init", { theme: "light" }); // "light" | "dark" | "auto"
```

`"auto"` follows the visitor's `prefers-color-scheme`.

## Custom design tokens

Pass a token object instead of a name to match your brand. Tokens map to CSS
custom properties inside the banner's shadow root, and any token you omit falls
back to the base:

```js
lightning("init", {
  theme: {
    surface: "#ffffff",
    text: "#14151a",
    accent: "#ffd400",
    accentText: "#14151a",
    border: "#e5e7eb",
    radius: "10px",
    fontFamily: "Inter, system-ui, sans-serif",
    // …textMuted, secondary, secondaryText, overlay
  },
});
```

### Which base do the tokens merge over?

A custom theme is your tokens layered on top of a base. Choose that base with an
optional `base` key — **`"auto"` (the default), `"light"`, or `"dark"`**:

```js
lightning("init", {
  theme: {
    base: "auto", // "auto" (default) | "light" | "dark"
    accent: "#ffd400",
  },
});
```

- **`"auto"`** — follows the visitor's `prefers-color-scheme`, so the _same_
  tokens sit on the light base by day and the dark base at night. Supply only
  the tokens that should differ from the built-in base (typically `accent`,
  `radius`, `fontFamily`) and they carry across both schemes.
- **`"light"` / `"dark"`** — pins the base for every visitor, ignoring their OS
  setting.

:::tip[Legibility is preserved across schemes]
With `base: "auto"`, if you override a background (`surface`, `secondary`,
`accent`) but not its text companion, the CMP re-derives that text colour for
the active base so it never turns light-on-light at night. A custom `border`
likewise snaps to the active base's divider unless you also set `surface`. To
take full manual control of a scheme, pin `base` and set every token you need.
:::

:::tip[Contrast is checked for you]
In [debug mode](/guides/verifying/) the CMP warns if a custom theme fails WCAG
2.1 AAA contrast. The built-in themes all pass.
:::

## Privacy-policy link

Set `privacyPolicyUrl` to show a link to your privacy policy in the preferences
modal footer (it opens in a new tab). Omit it and no link appears. The link
label is customisable via [`text.privacyPolicy`](/configure/copy-and-locales/).

```js
lightning("init", {
  privacyPolicyUrl: "https://example.com/privacy",
  text: { privacyPolicy: "Privacy policy" }, // optional label override
});
```

## Position & floating button

```js
lightning("init", {
  position: "bottom", // "bottom" | "top" | "bottom-left" | "bottom-right"
  showFloatingButton: true, // persistent re-open button after a decision
  floatingButtonPosition: "bottom-left",
});
```

## White-labelling

```js
lightning("init", { hideBranding: true }); // hides the "Powered by Lightning" footer
```

:::note[More detail coming]
The full token list and examples are being migrated from `docs/INSTALL.md` §
_“Theming & white-labelling.”_
:::