API參考·核心主題

@oriatheme/core

主題契約、驗證、解析和匯入/匯出 API，不具有 DOM、儲存、React 或 Vue 依賴性。

包裝及環境

純品TypeScript；在 Node、SSR 和瀏覽器模組評估中是安全的。

bash

pnpm add @oriatheme/core

bash

npm install @oriatheme/core

bash

yarn add @oriatheme/core

bash

bun add @oriatheme/core

使用消費者專案已經選擇的套件管理器和鎖定檔案。範例僅使用包根匯出；不要從 src、dist 或註冊表範本深度匯入。

公共職能

出口	簽名	描述
`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開始預設合約是oria-standard@2）；TokenContract描述了路徑和安全值； ValidationResult / ImportResult 區分就ok； OriaThemeError.code 是穩定錯誤分支。 ResolvedTheme 包含已編譯的變數和 colorScheme。 ThemeMigrationResult 攜帶遷移後的主題、警告和requiresReview。