For application developers

Custom themes

Copy immutable presets, save only after complete validation, and keep import, preview, and persistence within the runtime’s atomic boundary.

Presets are immutable

const copied = runtime.duplicateTheme("oria-default", {
  id: "brand-2026",
  name: "Brand 2026",
});

runtime.updateCustomTheme(copied.id, {
  name: "Brand 2026 (refined)",
  modes: { light: draftLightTokens, dark: draftDarkTokens },
});
runtime.setTheme(copied.id);

duplicateTheme creates a custom theme. Presets cannot be changed or deleted; removing the active custom theme falls back to the configured default.

Preview is not persistence

previewTheme applies only the current complete valid draft without changing preference or Storage. Disposing its handle restores the latest official state. Saving through createCustomTheme or updateCustomTheme validates completely before writing.

Import always passes through the contract

try {
  const imported = runtime.importTheme(json);
  runtime.setTheme(imported.id);
} catch (error) {
  // Branch on OriaThemeError.code, not its English message.
}

An import becomes a custom theme and cannot overwrite a preset; invalid JSON or tokens never partly apply. Present OriaThemeError.code or validation issues instead of matching error text.

Continue: application-defined presets