@stridge/noctis-theme-engine

@stridge/noctis-theme-engine

The framework-agnostic OKLCH theme generator at the base of the design system. From a { background, accent, contrast } input it produces the complete private primitive ramp (--noctis-engine-*) — plus the elevation-scope re-derivations — as CSS variables, with APCA-guaranteed text contrast. @stridge/noctis-design-tokens maps this output to intent-named semantic roles; only the semantic layer consumes the engine primitives, never components directly.

Usage

Consumers reach it through the umbrella package as @stridge/noctis/theme (+ /theme/react); it is also publishable standalone as @stridge/noctis-theme-engine.

import { generateTheme, applyTheme } from "@stridge/noctis-theme-engine";

const theme = generateTheme({ background: "#0b0b0c", accent: "#3b82f6", contrast: 1 });
applyTheme(document.documentElement, theme);

The core exports include generateTheme / generateScopeTheme, the applyTheme / applyScopeTheme / applyEngineVars appliers, the OKLCH color toolkit (parseColor, mix, adjust, toCss, …), the APCA/WCAG contrast solvers (apcaContrast, solveTextColor, …), the presets / defaultPreset catalog, and the ThemeInput / ThemeMap / ElevationLevel types.

// React bindings — @stridge/noctis-theme-engine/react
import { ThemeProvider, useTheme } from "@stridge/noctis-theme-engine/react";

<ThemeProvider>{children}</ThemeProvider>;

Build & checks

build runs tsdown; check:publish runs publint. React is an optional peer dependency.

See /AGENTS.md for repo-wide rules and @stridge/noctis-design-tokens for how engine primitives become semantic roles.