API reference · Core themes

@oriatheme/core

Theme-contract, validation, resolution, and import/export APIs with no DOM, Storage, React, or Vue dependency.

Package and environment

Pure TypeScript; safe in Node, SSR, and browser module evaluation.

bash

pnpm add @oriatheme/core

bash

npm install @oriatheme/core

bash

yarn add @oriatheme/core

bash

bun add @oriatheme/core

Use the package manager and lockfile already chosen by the consumer project. Examples use package-root exports only; do not deep-import from src, dist, or registry templates.

Public functions

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.
}

Branch on validateTheme or importTheme results for user input; do not match error messages.

Important types and boundaries

ThemeDefinition is the complete serialized theme (schemaVersion 1; the default contract is oria-standard@2 since 0.3.0); TokenContract describes paths and safe values; ValidationResult / ImportResult discriminate on ok; OriaThemeError.code is the stable error branch. ResolvedTheme contains compiled variables and colorScheme. ThemeMigrationResult carries the migrated theme, warnings, and requiresReview.