> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puntego.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Design tokens

> Match Puntego's semantic light and dark surfaces when you render controlled headless Guide and Experience state.

The built-in widget owns its closed Shadow DOM and reads brand settings from
the workspace. If you use the controlled headless SDK, your product owns the
markup and styling. `@puntego/embed/tokens` exposes the same semantic light and
dark palette so that custom UI can feel native without copying private runtime
selectors.

> **Release preview:** The token contract is implemented and tested, but
> `@puntego/embed` has not yet been published to npm. The import below becomes
> externally installable only after that package release; it is not a current
> npm availability claim.

```ts theme={null}
import {
  PUNTEGO_EMBED_THEME_TOKENS,
  puntegoEmbedCssVariables,
} from '@puntego/embed/tokens';

const root = document.querySelector<HTMLElement>('[data-puntego-headless]');

if (root) {
  for (const [name, value] of Object.entries(puntegoEmbedCssVariables('light'))) {
    root.style.setProperty(name, value);
  }
}

const receiptColor = PUNTEGO_EMBED_THEME_TOKENS.light.successText;
```

The public contract is semantic: `surface`, `text`, `border`, `primary`,
`inverse`, `success`, `danger`, `info`, `overlay`, three shadow levels, and
the accent family (`accent`, `accentStrong`, `action`, `actionHover`,
`onAction`, `focusRing`), and the chart marks after the accent (`chart2` …
`chart5`: a chart's second series, then a donut's further parts, neutral
steps that stand 3:1 off the surface in each theme). The accent family holds
the built-in widget's neutral blue default; the built-in widget replaces it
with your site's accent at runtime, so a headless UI should set its own.
Every name exists in both themes. Import the JavaScript object for React,
CSS-in-JS, or a token exporter; use `puntegoEmbedCssVariables()` when plain CSS
custom properties fit better.

## Figma mapping

Create a `Puntego / Light` and `Puntego / Dark` variable collection and map the
camel-case keys directly. Keep components bound to semantic variables—for
example `surfaceRaised`, `textMuted`, and `successText`—instead of pasting hex
values. This makes a future token update reviewable and keeps contrast pairs
together.

The accent chosen in **Dashboard → Settings → Brand** is tenant data, not a fixed package
token. Apply that value as your own brand/accent variable. Do not infer it from
Puntego's closed Shadow DOM.

## Boundaries

* Tokens style customer-rendered headless components; they do not unlock or
  restyle the built-in closed-shadow widget. The built-in widget has its own
  appearance contract (`appearance`, `--puntego-*` properties and `::part()`
  names): see [Appearance](/configuration#appearance).
* They do not change consent, action confirmation, policy, postconditions, or
  audit behavior.
* Puntego does not expose runtime class names, arbitrary CSS injection, or a
  hidden Figma dependency as part of this contract.
* Maintain accessible contrast and focus treatment when combining a custom
  accent with these surfaces.

See [Headless SDK](/headless-sdk) for the rendering and security contract and
[Configuration](/configuration#appearance) for the built-in widget's appearance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.