Theming & Tokens

The default Helpway widget ships with a clean light + dark theme out of the box, but every visual primitive — surface colors, text contrast, brand accent, border radius — is exposed as a CSS variable on the widget root (.hw-widget). Override one variable in your own stylesheet and every component picks it up.

Quick start

/* in your app's global stylesheet, after Helpway's CSS loads */
.hw-widget {
  --hw-brand: #7c5cff;     /* your accent color */
  --hw-on-brand: #ffffff;  /* foreground that sits on --hw-brand */
  --hw-radius: 14px;       /* corner softness */
}

That's it. Team avatars, primary CTAs, and any future brand-tinted surface adopt the new color immediately.

Dark mode

Three modes — pick one:

<HelpwayWidget apiKey="pk_live_xxx" theme="dark" />

When dark is active, every token below switches to its dark value — including --hw-brand, which inverts so a dark brand color stays visible on dark surfaces.

Token reference

All tokens live on .hw-widget. Override them on the same selector (or its inline style) to retheme.

Surfaces

Text

Brand

Note: --hw-brand and --hw-on-brand come as a pair. If you set a custom --hw-brand, set --hw-on-brand too to guarantee contrast — the default #fff will not work on a light brand.

Bubbles

Focus & interaction

Geometry & typography

Runtime tokens (don't override)

These are set programmatically by the widget. Listed for completeness:

• --hw-position-left / --hw-position-right — launcher anchor
• --hw-window-left / --hw-window-right — open window anchor
• --hw-visible-height — viewport height tracker (mobile keyboard)

Recipes

Indigo brand on white

.hw-widget {
  --hw-brand: #4f46e5;
  --hw-on-brand: #ffffff;
}

Brand color that stays consistent in dark mode

By default --hw-brand flips for contrast. If you want your exact brand color in both modes, override it in the dark scope too:

.hw-widget,
.hw-widget[data-theme="dark"] {
  --hw-brand: #7c5cff;
  --hw-on-brand: #ffffff;
}

Match host font

.hw-widget {
  --hw-font: "Inter", -apple-system, sans-serif;
}

Tighter, sharper corners

.hw-widget {
  --hw-radius: 10px;
}

Things to avoid

• Don't invent token names. var(--hw-surface) or var(--hw-text-muted) won't resolve — they aren't defined. CSS variable fallbacks fail silently, so a typo will look like a dark-mode bug. The complete list is the table above.
• Don't override hex inside selectors. Prefer overriding the token at the .hw-widget root. That way every selector that reads the token (including future ones) picks up your value.
• Don't override --hw-primary and --hw-brand to different values. They serve overlapping roles today; pick one as your accent and let the other inherit.

What's not (yet) tokenized

• Bubble corner radius — uses --hw-radius indirectly but not configurable per-side.
• Animation timings — currently hard-coded cubic-bezier(0.23, 1, 0.32, 1).
• Composer attachment chips — share the surface tokens but no dedicated knob yet.