Customize the widget and mobile SDKs consistently

Define one shared appearance

Keep the shared appearance object in your design configuration and pass it to the web SDK at initialization or through updateAppearance. Pass the same object as the native widget appearance option. Supported values include system, lightSurfaceStyle, palette tokens, font metrics, control radius, panel border and dimensions. Invalid values reject the complete update rather than partially changing the surface.

Use platform overrides only for a real platform constraint such as safe-area placement or a native navigation handoff. Do not fork the full theme for every framework. Native widget UI remains native and does not render the web widget in a WebView.

const sharedAppearance = {
  mode: "system",
  lightSurfaceStyle: "white",
  tokens: {
    light: { accent: "#2457d6", onAccent: "#ffffff", surface: "#ffffff", text: "#182230" },
    dark: { accent: "#91b4ff", onAccent: "#101828", surface: "#171b23", text: "#f2f4f7" },
  },
};
const platformOverrides = {
  safeArea: { topPx: 0, rightPx: 0, bottomPx: 0, leftPx: 0 },
  keyboard: { resizeMode: "resize", dismissOnSubmit: true },
};

const webWidget = createDobroDeskWidget({
  integrationId: "wgt_0123456789abcdef0123456789abcdef",
  appearance: sharedAppearance,
});
webWidget.updateAppearance(sharedAppearance);

await mobileClient.presentWidget({
  appearance: sharedAppearance,
  platform: platformOverrides,
});

Respect motion and native layout

Do not force animations by default. When the option is omitted, the web and native SDKs follow the current system reduced-motion preference. If your product has an explicit accessible motion setting, pass that user choice deliberately and keep it synchronized with the host.

The native presenter owns safe areas, keyboard movement, focus and platform transitions. Keep host controls outside the presented surface and hide an app-owned launcher while the widget is open so two controls do not compete for the same action.

Localize built-in and host-authored copy

The built-in native UI ships with en, uk, de and es. The web widget ships with en, uk, de, es, fr and pt. The native appearance contract lets a lower-level native renderer override the main widget UI copy keys, so a native surface can show French or Portuguese main UI text. This does not provide a complete French or Portuguese SDK locale: derived labels such as author-role labels, procedure and validation statuses and other generated UI still follow the built-in locale catalog.

Framework wrappers keep presentWidget options intentionally small: locale, title and subtitle. Do not treat those wrapper options as a full copy catalog or claim that native UI has the web widget's six built-in locales. A copy override does not expand the SDK locale enum, change number or date formatting or translate authored or server-authored content.

Localize authored FAQ entries, messages and other customer content in your own application or backend. Use the same appearance and copy contract across platform reference pages, then keep platform-specific overrides narrow.

Update appearance without losing work

1. Apply a runtime appearance update only after validating the complete object against the published schema and contrast limits.
2. Check the rendered widget in light, dark, system and reduced-motion modes. Confirm that the active conversation and composer draft remain intact after the update.
3. Keep unknown platform keys out of the shared object. A rejected update should leave the last valid appearance in place and show a recoverable host error.