API 参考 · 核心主题

@oriatheme/core

无 DOM、Storage、React 或 Vue 依赖的 Theme Contract、校验、解析和导入导出 API。

包与运行环境

纯 TypeScript；可在 Node、SSR 和浏览器模块求值中使用。

bash

pnpm add @oriatheme/core

bash

npm install @oriatheme/core

bash

yarn add @oriatheme/core

bash

bun add @oriatheme/core

选择使用方项目已有的一种包管理器和 lockfile；示例只使用 package root export，不要从 src、dist 或 registry template 深层导入。

公开函数

出口	签名	描述
`defineTokenContract`	`(input: TokenContractInput) => TokenContract`	创建一个不可变的、经过验证的合同。
`extendTokenContract`	`(base, extension) => TokenContract`	在不失去基础的情况下添加合约代币。
`getTokenDefinition`	`(contract, path) => TokenDefinition \| undefined`	查找已声明的令牌。
`token / colorToken`	`(type, options) => TokenDefinition`	创建合约代币定义。
`validateTheme`	`(input, contract) => ValidationResult<ThemeDefinition>`	永远不会抛出不受信任的序列化输入。
`normalizeTheme`	`(theme, contract) => ThemeDefinition`	规范化订单并填充合同默认值。
`resolveTheme`	`(theme, mode, options?) => ResolvedTheme`	解析引用并编译安全的 CSS 变量。
`resolveThemeWithContract`	`(theme, contract, mode, options?) => ResolvedTheme`	具有明确合同的安全解析器。
`cloneTheme`	`(theme, identity, clock?) => ThemeDefinition`	制作带时间戳的完整副本。
`createThemeFromSeed`	`(seed, options) => ThemeDefinition`	创建完整的标准合同自定义主题。
`exportTheme`	`(theme) => string`	序列化公共主题格式。
`importTheme`	`(json, options) => ImportResult`	验证 JSON、强制自定义类型并处理冲突。
`analyzeTheme`	`(theme, contract) => ThemeDiagnostics`	返回阻塞错误和对比警告。
`contrastRatio`	`(foreground, background) => number`	计算静态十六进制颜色的 WCAG 对比度。
`toCssVariable`	(path, prefix?, cssNameStyle?) => `--${string}`	将经过验证的路径转换为 CSS 自定义属性。
`isTokenPath`	`(value) => value is TokenPath`	将字符串缩小为品牌标记路径。
`oriaStandardContract / oriaDefaultTheme`	`TokenContract / ThemeDefinition`	从 0.3.0 开始默认的 oria-standard@2 合约和默认主题。
`oriaStandardContractV1 / oriaDefaultThemeV1`	`TokenContract / ThemeDefinition`	旧版 v1 导出仅保留作为迁移输入。
`migrateOriaStandardV1ToV2`	`(input: unknown) => ThemeMigrationResult`	将完整的 v1 标准主题转换为带有警告和 requireReview 的 v2。

import { oriaStandardContract, resolveTheme, validateTheme } from "@oriatheme/core";

const checked = validateTheme(input, oriaStandardContract);
if (checked.ok) {
  const resolved = resolveTheme(checked.value, "dark");
  // resolved.variables is safe compiler output.
}

对用户输入优先使用 validateTheme 或 importTheme 的结果分支；不要匹配错误文本。

重要类型与边界

ThemeDefinition 是完整序列化主题（schemaVersion 1；自 0.3.0 起默认 contract 为 oria-standard@2）；TokenContract 描述路径和安全值类型；ValidationResult / ImportResult 以 ok 判别；OriaThemeError 的 code 是稳定错误分支。ResolvedTheme 包含已编译的变量和 colorScheme。ThemeMigrationResult 携带迁移后主题、warnings 与 requiresReview。