Design tokens

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.

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.
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 for the rendering and security contract and Configuration for the built-in widget’s appearance.

Get started

Integrate

Deploy & security

Resources

Figma mapping

Boundaries

​Figma mapping

​Boundaries

Figma mapping

Boundaries