Lovelace

Overview

Lovelace is the design system that Ada’s own messaging app is built from. It is published to npm as @ada-cx/lovelace: a library of React components, design tokens, and theming utilities for building chat interfaces.

Use Lovelace when you build your own conversation UI instead of rendering Ada’s default widget. It pairs with two integration paths:

  • Headless Web SDK: run the Messaging SDK with headless: true and drive the conversation through the programmatic API, while Lovelace components render your custom surface on the page.
  • Custom app frames: build a replacement conversation UI that Ada mounts in place of its default app, driven by @ada-cx/messaging-bridge.

See Build a custom chat UI for a worked example of both paths.

What the package contains

  • Components: message bubbles, composer inputs, buttons, overlays, survey controls, and supporting primitives. See the component catalog and its live gallery.
  • Design tokens: a tiered set of CSS custom properties (--lovelace-*) that carry every color, font, spacing, and radius value. See Theming.
  • Brand mapping: createBrandOverrides converts your Ada dashboard brand settings into token overrides. It is the same function the hosted widget runs. See How Ada applies your brand settings.
  • LovelaceProvider: the prescribed entry component. It resolves light and dark themes, applies token overrides, and scopes overlay portals.
  • Hooks: useSubmitOnEnter, usePrefersReducedMotion, and useResolvedTheme.

Interactive behavior comes from React Aria Components. Components target WCAG 2.2 Level AA: keyboard operability, roles, and focus management are built in.

Scope of this release

Read this section before you commit to Lovelace. It states the deliberate limits of the current release.

  • Primitives only. The package ships design system primitives: buttons, inputs, chips, dialogs, sheets, survey controls, icons, and similar building blocks. Domain composites from the Ada product, such as the CSAT survey form and the file-upload flow, are not included.
  • React 19 is a hard requirement. The peer dependency range is ^19.0.0 for react and react-dom. Earlier React versions are not supported, and the range will not be widened.
  • Pixel parity with the Ada widget is not guaranteed. The hosted Ada messaging app blends Lovelace with a legacy component system during an incremental migration. A UI you build from these primitives can differ visually from the hosted widget.

Versioning

@ada-cx/lovelace is fully versioned: the implementation you install is the implementation you run. Pin a version and upgrade deliberately.

This differs from Ada’s web messaging runtime, which resolves from Ada’s CDN at load time and updates automatically.

Resources

  • Getting started: install the package and render your first component.
  • Theming: the token system, overrides, dark mode, brand settings, and the interactive theme playground.
  • Components: the full component catalog with a live gallery.
  • Build a custom chat UI: wire Lovelace to a live conversation.