API 참조 · 핵심 테마

@oriatheme/core

DOM, Storage, React 또는 Vue 종속성이 없는 테마 계약, 유효성 검사, 해결 및 가져오기/내보내기 API입니다.

패키지 및 환경

순수 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`	정적 16진수 색상에 대한 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 표준 테마를 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.
}

사용자 입력에 대한 verifyTheme 또는 importTheme 결과를 분기합니다. 오류 메시지가 일치하지 않습니다.

중요한 유형 및 경계

ThemeDefinition은 완전히 직렬화된 테마입니다(schemaVersion 1, 기본 계약은 0.3.0부터 oria-standard@2입니다). TokenContract는 경로와 안전한 값을 설명합니다. ValidationResult / ImportResult는 확인을 차별합니다. OriaThemeError.code는 안정적인 오류 분기입니다. ResolvedTheme에는 컴파일된 변수와 colorScheme이 포함되어 있습니다. ThemeMigrationResult는 마이그레이션된 테마, 경고 및 requireReview를 전달합니다.