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 深层导入。

公开函数

Export	Signature	Description
`defineTokenContract`	`(input: TokenContractInput) => TokenContract`	Creates an immutable, validated contract.
`extendTokenContract`	`(base, extension) => TokenContract`	Adds contract tokens without losing the base.
`getTokenDefinition`	`(contract, path) => TokenDefinition \| undefined`	Looks up a declared token.
`token / colorToken`	`(type, options) => TokenDefinition`	Creates contract-token definitions.
`validateTheme`	`(input, contract) => ValidationResult<ThemeDefinition>`	Never throws for untrusted serialized input.
`normalizeTheme`	`(theme, contract) => ThemeDefinition`	Canonicalizes order and fills contract defaults.
`resolveTheme`	`(theme, mode, options?) => ResolvedTheme`	Resolves references and compiles safe CSS variables.
`resolveThemeWithContract`	`(theme, contract, mode, options?) => ResolvedTheme`	Safe resolver with an explicit contract.
`cloneTheme`	`(theme, identity, clock?) => ThemeDefinition`	Makes a timestamped complete copy.
`createThemeFromSeed`	`(seed, options) => ThemeDefinition`	Creates a complete standard-contract custom theme.
`exportTheme`	`(theme) => string`	Serializes the public theme format.
`importTheme`	`(json, options) => ImportResult`	Validates JSON, forces custom kind, and handles conflicts.
`analyzeTheme`	`(theme, contract) => ThemeDiagnostics`	Returns blocking errors and contrast warnings.
`contrastRatio`	`(foreground, background) => number`	Computes WCAG contrast for static hex colors.
`toCssVariable`	(path, prefix?, cssNameStyle?) => `--${string}`	Converts a validated path to a CSS custom property.
`isTokenPath`	`(value) => value is TokenPath`	Narrows a string to a branded token path.
`oriaStandardContract / oriaDefaultTheme`	`TokenContract / ThemeDefinition`	The default oria-standard@2 contract and default theme since 0.3.0.
`oriaStandardContractV1 / oriaDefaultThemeV1`	`TokenContract / ThemeDefinition`	Legacy v1 exports retained only as migration input.
`migrateOriaStandardV1ToV2`	`(input: unknown) => ThemeMigrationResult`	Converts a complete v1 standard theme to v2 with warnings and requiresReview.

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。