应用开发者

从 v1 迁移

oria-standard@2 是默认且唯一的标准 Contract：显式注册迁移、复核几何取整，并让 Bootstrap 拒绝旧快照。

默认 Contract 已切换

自 core 0.3.0 起，不传 contract 的 Core/Runtime API 均解析 oria-standard@2：134 个 source token、全小写 kebab-case CSS 变量与声明式派生变量。v1 仅以 legacy 导出保留为迁移输入（oriaStandardContractV1、oriaDefaultThemeV1、migrateOriaStandardV1ToV2）；官方预设原生 v2 且 ID 不变。v1 的 camelCase 变量（如 --oria-color-background、--oria-typography-size-md、--oria-spacing-4）不再输出，应用自有样式需改为 v2 命名（--oria-color-bg、--oria-text-md、calc(var(--oria-space) * 4）。

显式注册迁移器

用户可能持有 v1 custom theme（Storage 或导出的 JSON）时，在 Runtime config 注册迁移器。注册后，持久化的 v1 主题在首次启动时迁移、完整校验、原子应用并写回 Storage；未注册时 v1 数据被整体安全拒绝，且不会在该次启动中覆盖原数据。

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

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

requiresReview 复核

v2 几何只持久化 space 与 radius 两个长度来源：半径是固定倍数，控件尺寸是 space 的 1–24 整数倍。无法精确表示的 v1 值会取最近合法值并逐字段发出 warning；存在 warning 时迁移结果的 requiresReview 为 true。经 Core importTheme 导入可取得 warnings 与 requiresReview，应让用户预览并确认后再保存；Runtime 的 importTheme 自动使用已注册迁移器，但不携带 warnings。

Bootstrap 拒绝旧快照

为 bootstrapTheme 或 createBootstrapStorageScript 传入 v2 contract 后，v1 时代写入的 active snapshot 会被安全拒绝，页面保持静态默认 CSS，直到 Runtime 首次应用 v2 主题并写入新快照；未声明 contract 时不执行这项检查。

继续：Runtime 配置