For application developers

Migrate from v1

oria-standard@2 is the default and only standard contract: register an explicit migration, review geometry rounding, and let Bootstrap reject stale snapshots.

The default contract has switched

Since core 0.3.0, Core/Runtime APIs called without a contract resolve oria-standard@2: 134 source tokens, lowercase kebab-case CSS variables, and declared derived variables. v1 remains only as legacy exports for migration input (oriaStandardContractV1, oriaDefaultThemeV1, migrateOriaStandardV1ToV2). Official presets are native v2 with unchanged IDs. v1 camelCase variables (such as --oria-color-background, --oria-typography-size-md, --oria-spacing-4) are no longer emitted; update your own styles to v2 names (--oria-color-bg, --oria-text-md, calc(var(--oria-space) * 4)).

Register the migrator explicitly

If your users may hold v1 custom themes (Storage or exported JSON), register the migrator in the runtime config. Persisted v1 themes are then migrated, fully validated, atomically applied, and written back on first start; without registration, v1 data is rejected as a whole and left untouched during that launch.

import { migrateOriaStandardV1ToV2 } from "@oriatheme/core";
import { oriaPresetThemes } from "@oriatheme/presets";

createOriaThemeRuntime({
  presets: oriaPresetThemes,
  defaultThemeId: "oria-default",
  migrations: [migrateOriaStandardV1ToV2],
});

The requiresReview flow

v2 persists only two geometry sources, space and radius: radii are fixed multiples, and control sizes are integer multiples of space from 1 to 24. A v1 value that cannot be represented exactly snaps to the nearest legal value and emits a per-field warning; requiresReview is true whenever any warning exists. Core's importTheme returns warnings and requiresReview so users can preview and confirm before saving; the runtime's importTheme applies registered migrations automatically but does not carry warnings.

Bootstrap rejects stale snapshots

Passing the v2 contract to bootstrapTheme or createBootstrapStorageScript makes v1-era active snapshots reject safely, keeping the static default CSS until the runtime applies a v2 theme and writes a fresh snapshot. Without the declaration, no such check runs.

Continue: runtime configuration