@lmring/theme 1.0.0

package/README.md

@@ -0,0 +1,18 @@
+# @lmring/theme
+
+Theme engine, design tokens, and CSS variable utilities for LMRing.
+
+## Install
+
+```bash
+pnpm add @lmring/theme
+```
+
+## Usage
+
+```ts
+import { getPreset, paletteToCssVars } from "@lmring/theme";
+import "@lmring/theme/css";
+
+const cssVars = paletteToCssVars(getPreset("ocean-blue"));
+```

package/dist/index.d.ts

@@ -0,0 +1,253 @@
+//#region src/types.d.ts
+/**
+ * Core type definitions for @lmring/theme
+ *
+ * All color values use the OKLCH color space for perceptual uniformity.
+ */
+/** A color in the OKLCH color space. */
+interface OklchColor {
+  /** Lightness: 0–1 */
+  l: number;
+  /** Chroma: 0–0.4 */
+  c: number;
+  /** Hue: 0–360 */
+  h: number;
+}
+/** Full set of semantic color slots used by the design system. */
+interface SemanticPalette {
+  primary: OklchColor;
+  primaryForeground: OklchColor;
+  secondary: OklchColor;
+  secondaryForeground: OklchColor;
+  accent: OklchColor;
+  accentForeground: OklchColor;
+  muted: OklchColor;
+  mutedForeground: OklchColor;
+  destructive: OklchColor;
+  destructiveForeground: OklchColor;
+  background: OklchColor;
+  foreground: OklchColor;
+  card: OklchColor;
+  cardForeground: OklchColor;
+  border: OklchColor;
+  input: OklchColor;
+  ring: OklchColor;
+}
+/** Light and dark mode palettes derived from a seed color. */
+interface ThemePalette {
+  light: SemanticPalette;
+  dark: SemanticPalette;
+}
+/** Serializable theme configuration stored in localStorage / server DB. */
+interface PersistedThemeConfig {
+  mode: 'light' | 'dark' | 'system';
+  seedColor: OklchColor;
+  presetName: string | null;
+}
+/** A named preset theme with its OKLCH seed parameters. */
+interface ThemePreset {
+  name: string;
+  hue: number;
+  chroma: number;
+  lightness: number;
+}
+//#endregion
+//#region src/color-convert.d.ts
+/**
+ * Convert a HEX color string to an OKLCH color object.
+ *
+ * @param hex - A valid 3 or 6 digit HEX string with `#` prefix (e.g. `#ff0000`, `#f00`)
+ * @returns The color in OKLCH space
+ * @throws If the HEX string is invalid
+ */
+declare function hexToOklch(hex: string): OklchColor;
+/**
+ * Convert an OKLCH color object back to a 6-digit HEX string.
+ *
+ * @param color - An OKLCH color
+ * @returns A HEX string like `#rrggbb`
+ */
+declare function oklchToHex(color: OklchColor): string;
+/**
+ * Format an OKLCH color as a CSS `oklch()` function string.
+ *
+ * @param color - An OKLCH color
+ * @returns A string like `oklch(0.5 0.2 270)`
+ */
+declare function oklchToCss(color: OklchColor): string;
+//#endregion
+//#region src/contrast.d.ts
+/**
+ * Compute the WCAG 2.1 relative luminance of an OKLCH color.
+ *
+ * Converts the color to sRGB, linearizes each channel, then applies
+ * the standard luminance coefficients: 0.2126·R + 0.7152·G + 0.0722·B.
+ *
+ * @param color - An OKLCH color
+ * @returns Relative luminance in [0, 1]
+ */
+declare function getRelativeLuminance(color: OklchColor): number;
+/**
+ * Compute the WCAG 2.1 contrast ratio between two OKLCH colors.
+ *
+ * The ratio is always ≥ 1, with 21:1 being the maximum (black on white).
+ *
+ * @param fg - Foreground color
+ * @param bg - Background color
+ * @returns Contrast ratio (e.g. 4.5 means 4.5:1)
+ */
+declare function getContrastRatio(fg: OklchColor, bg: OklchColor): number;
+/**
+ * Check whether two OKLCH colors meet the WCAG 2.1 AA contrast requirement.
+ *
+ * - Normal text: contrast ratio ≥ 4.5:1
+ * - Large text (≥ 18pt or ≥ 14pt bold): contrast ratio ≥ 3.0:1
+ *
+ * @param fg - Foreground color
+ * @param bg - Background color
+ * @param isLargeText - Whether the text qualifies as "large" under WCAG
+ * @returns `true` if the pair meets WCAG AA
+ */
+declare function meetsWcagAA(fg: OklchColor, bg: OklchColor, isLargeText: boolean): boolean;
+//#endregion
+//#region src/color-engine.d.ts
+/**
+ * Generate a complete light + dark semantic palette from a seed OKLCH color.
+ *
+ * The seed color's hue drives the entire palette. Lightness and chroma
+ * are adjusted per semantic role according to the design system rules.
+ *
+ * @param seed - The user-chosen seed color in OKLCH space
+ * @returns A `ThemePalette` with `light` and `dark` semantic palettes
+ */
+declare function generatePalette(seed: OklchColor): ThemePalette;
+/**
+ * Deep-merge partial overrides into a base palette.
+ *
+ * Overridden keys take the override value; all other keys are preserved
+ * from the base. Always returns a new object (no mutation).
+ *
+ * @param base - The base palette to start from
+ * @param overrides - Partial light/dark overrides to apply
+ * @returns A new `ThemePalette` with overrides merged in
+ */
+declare function mergePalette(base: ThemePalette, overrides: Partial<{
+  light: Partial<SemanticPalette>;
+  dark: Partial<SemanticPalette>;
+}>): ThemePalette;
+//#endregion
+//#region src/presets.d.ts
+/**
+ * All available preset themes.
+ *
+ * Each preset uses a default chroma of 0.18 and lightness of 0.55,
+ * varying only in hue to produce distinct color families.
+ */
+declare const presets: ThemePreset[];
+/**
+ * Look up a preset by name and return its generated palette.
+ *
+ * @param name - Kebab-case preset name (e.g. 'ocean-blue', 'violet')
+ * @returns The full light + dark `ThemePalette` for the preset
+ * @throws {Error} If no preset matches the given name
+ */
+declare function getPreset(name: string): ThemePalette;
+//#endregion
+//#region src/tokens.d.ts
+/**
+ * Design tokens for @lmring/theme
+ *
+ * Static design tokens covering spacing, radius, shadow, typography,
+ * line-height (leading), easing, and duration values.
+ *
+ * Spacing uses a 4px base grid. All numeric spacing values (excluding 0)
+ * are positive multiples of 4.
+ */
+/** All design tokens grouped by category */
+declare const tokens: {
+  readonly spacing: {
+    readonly 0: "0px";
+    readonly 1: "4px";
+    readonly 2: "8px";
+    readonly 3: "12px";
+    readonly 4: "16px";
+    readonly 5: "20px";
+    readonly 6: "24px";
+    readonly 8: "32px";
+    readonly 10: "40px";
+    readonly 12: "48px";
+    readonly 16: "64px";
+  };
+  readonly radius: {
+    readonly sm: "calc(var(--radius) - 4px)";
+    readonly md: "calc(var(--radius) - 2px)";
+    readonly lg: "var(--radius)";
+    readonly xl: "calc(var(--radius) + 4px)";
+    readonly '2xl': "calc(var(--radius) + 8px)";
+    readonly full: "9999px";
+  };
+  readonly shadow: {
+    readonly sm: "0 1px 2px oklch(0 0 0 / 3%), 0 1px 3px oklch(0 0 0 / 2%)";
+    readonly md: "0 2px 4px oklch(0 0 0 / 3%), 0 4px 8px oklch(0 0 0 / 3%), 0 8px 16px oklch(0 0 0 / 2%)";
+    readonly lg: "0 4px 8px oklch(0 0 0 / 3%), 0 8px 16px oklch(0 0 0 / 3%), 0 16px 32px oklch(0 0 0 / 4%), 0 32px 64px oklch(0 0 0 / 2%)";
+  };
+  readonly typography: {
+    readonly xs: "0.75rem";
+    readonly sm: "0.875rem";
+    readonly base: "1rem";
+    readonly lg: "1.125rem";
+    readonly xl: "1.25rem";
+    readonly '2xl': "1.5rem";
+    readonly '3xl': "1.875rem";
+    readonly '4xl': "2.25rem";
+  };
+  readonly leading: {
+    readonly tight: "1.25";
+    readonly snug: "1.375";
+    readonly normal: "1.5";
+    readonly relaxed: "1.625";
+    readonly loose: "1.75";
+  };
+  readonly easing: {
+    readonly spring: "cubic-bezier(0.34, 1.56, 0.64, 1)";
+    readonly smooth: "cubic-bezier(0.25, 0.1, 0.25, 1)";
+    readonly outExpo: "cubic-bezier(0.16, 1, 0.3, 1)";
+  };
+  readonly duration: {
+    readonly fast: "150ms";
+    readonly normal: "200ms";
+    readonly slow: "300ms";
+    readonly slower: "500ms";
+  };
+};
+//#endregion
+//#region src/css-generator.d.ts
+/**
+ * Convert a SemanticPalette into a Record of CSS custom properties.
+ *
+ * Each key in the palette is converted from camelCase to a `--kebab-case`
+ * CSS variable name, and each value is formatted as an `oklch(l c h)` string.
+ *
+ * @param palette - A semantic palette (light or dark)
+ * @returns A record mapping CSS variable names to OKLCH CSS values
+ *
+ * @example
+ * paletteToCssVars(palette)
+ * // { '--primary': 'oklch(0.55 0.18 255)', '--primary-foreground': 'oklch(1 0 0)', ... }
+ */
+declare function paletteToCssVars(palette: SemanticPalette): Record<string, string>;
+//#endregion
+//#region src/persistence.d.ts
+/** Serialize a theme config to a JSON string. */
+declare function serialize(config: PersistedThemeConfig): string;
+/**
+ * Deserialize a raw JSON string into a validated {@link PersistedThemeConfig}.
+ *
+ * Returns `null` when:
+ * - the string is not valid JSON
+ * - any field fails validation (mode enum, OKLCH ranges, presetName type)
+ */
+declare function deserialize(raw: string): PersistedThemeConfig | null;
+//#endregion
+export { type OklchColor, type PersistedThemeConfig, type SemanticPalette, type ThemePalette, type ThemePreset, deserialize, generatePalette, getContrastRatio, getPreset, getRelativeLuminance, hexToOklch, meetsWcagAA, mergePalette, oklchToCss, oklchToHex, paletteToCssVars, presets, serialize, tokens };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/color-convert.ts","../src/contrast.ts","../src/color-engine.ts","../src/presets.ts","../src/tokens.ts","../src/css-generator.ts","../src/persistence.ts"],"mappings":";;AAOA;;;;;UAAiB,UAAA;EAMf;EAJA,CAAA;EAIC;EAFD,CAAA;EAM8B;EAJ9B,CAAA;AAAA;;UAIe,eAAA;EACf,OAAA,EAAS,UAAA;EACT,iBAAA,EAAmB,UAAA;EACnB,SAAA,EAAW,UAAA;EACX,mBAAA,EAAqB,UAAA;EACrB,MAAA,EAAQ,UAAA;EACR,gBAAA,EAAkB,UAAA;EAClB,KAAA,EAAO,UAAA;EACP,eAAA,EAAiB,UAAA;EACjB,WAAA,EAAa,UAAA;EACb,qBAAA,EAAuB,UAAA;EACvB,UAAA,EAAY,UAAA;EACZ,UAAA,EAAY,UAAA;EACZ,IAAA,EAAM,UAAA;EACN,cAAA,EAAgB,UAAA;EAChB,MAAA,EAAQ,UAAA;EACR,KAAA,EAAO,UAAA;EACP,IAAA,EAAM,UAAA;AAAA;;UAIS,YAAA;EACf,KAAA,EAAO,eAAA;EACP,IAAA,EAAM,eAAA;AAAA;;UAIS,oBAAA;EACf,IAAA;EACA,SAAA,EAAW,UAAA;EACX,UAAA;AAAA;;UAIe,WAAA;EACf,IAAA;EACA,GAAA;EACA,MAAA;EACA,SAAA;AAAA;;;;;;AAtCF;;;;iBCgBgB,UAAA,CAAW,GAAA,WAAc,UAAA;;;;;;;iBAmBzB,UAAA,CAAW,KAAA,EAAO,UAAA;;;;;;;iBAWlB,UAAA,CAAW,KAAA,EAAO,UAAA;;;;;;AD9ClC;;;;;;iBEcgB,oBAAA,CAAqB,KAAA,EAAO,UAAA;;;;;;;;;;iBAsB5B,gBAAA,CAAiB,EAAA,EAAI,UAAA,EAAY,EAAA,EAAI,UAAA;;;;;;;;;;;;iBAmBrC,WAAA,CACd,EAAA,EAAI,UAAA,EACJ,EAAA,EAAI,UAAA,EACJ,WAAA;;;;;;AF1DF;;;;;;iBG2FgB,eAAA,CAAgB,IAAA,EAAM,UAAA,GAAa,YAAA;;;;;;;;;;;iBAiBnC,YAAA,CACd,IAAA,EAAM,YAAA,EACN,SAAA,EAAW,OAAA;EACT,KAAA,EAAO,OAAA,CAAQ,eAAA;EACf,IAAA,EAAM,OAAA,CAAQ,eAAA;AAAA,KAEf,YAAA;;;;;;AHlHH;;;cIDa,OAAA,EAAS,WAAA;;;;;;;;iBAkBN,SAAA,CAAU,IAAA,WAAe,YAAA;;;;AJ3BzC;;;;;;;;;cKwEa,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AL9Db;;;;;;;;;;iBMegB,gBAAA,CAAiB,OAAA,EAAS,eAAA,GAAkB,MAAA;;;;iBCf5C,SAAA,CAAU,MAAA,EAAQ,oBAAA;APAlC;;;;;;;AAAA,iBOWgB,WAAA,CAAY,GAAA,WAAc,oBAAA"}

package/dist/index.js

@@ -0,0 +1,498 @@
+import { converter, formatHex } from "culori";
+
+//#region src/color-convert.ts
+/**
+* Color space conversion utilities.
+*
+* Converts between HEX, OKLCH, and CSS string representations
+* using the `culori` library for accurate color math.
+*/
+const toOklch = converter("oklch");
+const HEX_REGEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+/**
+* Validate that a string is a valid HEX color (#RGB or #RRGGBB).
+* Throws if the format is invalid.
+*/
+function assertValidHex(hex) {
+	if (!HEX_REGEX.test(hex)) throw new Error(`Invalid HEX color: "${hex}". Expected format: #RGB or #RRGGBB.`);
+}
+/**
+* Convert a HEX color string to an OKLCH color object.
+*
+* @param hex - A valid 3 or 6 digit HEX string with `#` prefix (e.g. `#ff0000`, `#f00`)
+* @returns The color in OKLCH space
+* @throws If the HEX string is invalid
+*/
+function hexToOklch(hex) {
+	assertValidHex(hex);
+	const result = toOklch(hex);
+	if (!result) throw new Error(`Failed to convert HEX "${hex}" to OKLCH.`);
+	return {
+		l: result.l,
+		c: result.c ?? 0,
+		h: result.h ?? 0
+	};
+}
+/**
+* Convert an OKLCH color object back to a 6-digit HEX string.
+*
+* @param color - An OKLCH color
+* @returns A HEX string like `#rrggbb`
+*/
+function oklchToHex(color) {
+	return formatHex({
+		mode: "oklch",
+		l: color.l,
+		c: color.c,
+		h: color.h
+	});
+}
+/**
+* Format an OKLCH color as a CSS `oklch()` function string.
+*
+* @param color - An OKLCH color
+* @returns A string like `oklch(0.5 0.2 270)`
+*/
+function oklchToCss(color) {
+	return `oklch(${color.l} ${color.c} ${color.h})`;
+}
+
+//#endregion
+//#region src/contrast.ts
+/**
+* WCAG 2.1 contrast ratio utilities.
+*
+* Computes relative luminance and contrast ratios for OKLCH colors
+* by converting through sRGB, following the WCAG 2.1 specification.
+*/
+const toRgb = converter("rgb");
+/**
+* Linearize a single sRGB channel value for luminance calculation.
+*
+* @param c - sRGB channel value in [0, 1]
+* @returns Linear RGB value
+*/
+function linearize(c) {
+	return c <= .04045 ? c / 12.92 : ((c + .055) / 1.055) ** 2.4;
+}
+/**
+* Compute the WCAG 2.1 relative luminance of an OKLCH color.
+*
+* Converts the color to sRGB, linearizes each channel, then applies
+* the standard luminance coefficients: 0.2126·R + 0.7152·G + 0.0722·B.
+*
+* @param color - An OKLCH color
+* @returns Relative luminance in [0, 1]
+*/
+function getRelativeLuminance(color) {
+	const rgb = toRgb({
+		mode: "oklch",
+		l: color.l,
+		c: color.c,
+		h: color.h
+	});
+	if (!rgb) return 0;
+	const r = linearize(Math.max(0, Math.min(1, rgb.r)));
+	const g = linearize(Math.max(0, Math.min(1, rgb.g)));
+	const b = linearize(Math.max(0, Math.min(1, rgb.b)));
+	return .2126 * r + .7152 * g + .0722 * b;
+}
+/**
+* Compute the WCAG 2.1 contrast ratio between two OKLCH colors.
+*
+* The ratio is always ≥ 1, with 21:1 being the maximum (black on white).
+*
+* @param fg - Foreground color
+* @param bg - Background color
+* @returns Contrast ratio (e.g. 4.5 means 4.5:1)
+*/
+function getContrastRatio(fg, bg) {
+	const l1 = getRelativeLuminance(fg);
+	const l2 = getRelativeLuminance(bg);
+	const lighter = Math.max(l1, l2);
+	const darker = Math.min(l1, l2);
+	return (lighter + .05) / (darker + .05);
+}
+/**
+* Check whether two OKLCH colors meet the WCAG 2.1 AA contrast requirement.
+*
+* - Normal text: contrast ratio ≥ 4.5:1
+* - Large text (≥ 18pt or ≥ 14pt bold): contrast ratio ≥ 3.0:1
+*
+* @param fg - Foreground color
+* @param bg - Background color
+* @param isLargeText - Whether the text qualifies as "large" under WCAG
+* @returns `true` if the pair meets WCAG AA
+*/
+function meetsWcagAA(fg, bg, isLargeText) {
+	const ratio = getContrastRatio(fg, bg);
+	return isLargeText ? ratio >= 3 : ratio >= 4.5;
+}
+
+//#endregion
+//#region src/color-engine.ts
+/**
+* Clamp a number to the given range.
+*/
+function clamp(value, min, max) {
+	return Math.min(max, Math.max(min, value));
+}
+/**
+* Normalize a hue value to [0, 360).
+*/
+function normalizeHue(h) {
+	return (h % 360 + 360) % 360;
+}
+/**
+* Create a valid OklchColor with clamped values.
+*/
+function oklch(l, c, h) {
+	return {
+		l: clamp(l, 0, 1),
+		c: clamp(c, 0, .4),
+		h: normalizeHue(h)
+	};
+}
+/**
+* Derive the light-mode semantic palette from a seed color.
+*/
+function generateLightPalette(seed) {
+	const h = normalizeHue(seed.h);
+	const primary = oklch(.52, seed.c, h);
+	return {
+		primary,
+		primaryForeground: oklch(1, 0, h),
+		secondary: oklch(.96, .005, h),
+		secondaryForeground: oklch(.25, .015, h),
+		accent: oklch(.96, .01, h),
+		accentForeground: oklch(.25, .015, h),
+		muted: oklch(.96, .005, h),
+		mutedForeground: oklch(.58, .01, h),
+		destructive: oklch(.55, .22, 25),
+		destructiveForeground: oklch(1, 0, 25),
+		background: oklch(.98, .002, h),
+		foreground: oklch(.2, .015, h),
+		card: oklch(1, 0, h),
+		cardForeground: oklch(.2, .015, h),
+		border: oklch(.9, .005, h),
+		input: oklch(.95, .005, h),
+		ring: primary
+	};
+}
+/**
+* Derive the dark-mode semantic palette from a seed color.
+*
+* Uses a layered surface system with increasing lightness:
+*   Layer 0 (background): L=0.14
+*   Layer 1 (card):       L=0.18
+*   Layer 2 (elevated):   L=0.22  (mapped to `input`)
+*   Layer 3 (overlay):    L=0.26  (mapped to `border` at L=0.28 per rules table)
+*/
+function generateDarkPalette(seed) {
+	const h = normalizeHue(seed.h);
+	const primary = oklch(.45, seed.c * .9, h);
+	return {
+		primary,
+		primaryForeground: oklch(.98, .005, h),
+		secondary: oklch(.25, .01, h),
+		secondaryForeground: oklch(.9, .005, h),
+		accent: oklch(.28, .015, h),
+		accentForeground: oklch(.9, .005, h),
+		muted: oklch(.25, .01, h),
+		mutedForeground: oklch(.72, .005, h),
+		destructive: oklch(.6, .24, 25),
+		destructiveForeground: oklch(.95, .01, 25),
+		background: oklch(.14, .01, h),
+		foreground: oklch(.95, .005, h),
+		card: oklch(.18, .01, h),
+		cardForeground: oklch(.95, .005, h),
+		border: oklch(.28, .01, h),
+		input: oklch(.22, .01, h),
+		ring: primary
+	};
+}
+/**
+* Generate a complete light + dark semantic palette from a seed OKLCH color.
+*
+* The seed color's hue drives the entire palette. Lightness and chroma
+* are adjusted per semantic role according to the design system rules.
+*
+* @param seed - The user-chosen seed color in OKLCH space
+* @returns A `ThemePalette` with `light` and `dark` semantic palettes
+*/
+function generatePalette(seed) {
+	return {
+		light: generateLightPalette(seed),
+		dark: generateDarkPalette(seed)
+	};
+}
+/**
+* Deep-merge partial overrides into a base palette.
+*
+* Overridden keys take the override value; all other keys are preserved
+* from the base. Always returns a new object (no mutation).
+*
+* @param base - The base palette to start from
+* @param overrides - Partial light/dark overrides to apply
+* @returns A new `ThemePalette` with overrides merged in
+*/
+function mergePalette(base, overrides) {
+	return {
+		light: {
+			...base.light,
+			...overrides.light
+		},
+		dark: {
+			...base.dark,
+			...overrides.dark
+		}
+	};
+}
+
+//#endregion
+//#region src/presets.ts
+/**
+* Preset theme definitions for @lmring/theme.
+*
+* Each preset is defined by its OKLCH hue angle. The color engine
+* generates a full semantic palette from the seed parameters.
+*/
+/**
+* All available preset themes.
+*
+* Each preset uses a default chroma of 0.18 and lightness of 0.55,
+* varying only in hue to produce distinct color families.
+*/
+const presets = [
+	{
+		name: "ocean-blue",
+		hue: 255,
+		chroma: .18,
+		lightness: .55
+	},
+	{
+		name: "violet",
+		hue: 280,
+		chroma: .18,
+		lightness: .55
+	},
+	{
+		name: "emerald",
+		hue: 155,
+		chroma: .18,
+		lightness: .55
+	},
+	{
+		name: "amber",
+		hue: 75,
+		chroma: .18,
+		lightness: .55
+	},
+	{
+		name: "rose",
+		hue: 350,
+		chroma: .18,
+		lightness: .55
+	},
+	{
+		name: "crimson",
+		hue: 25,
+		chroma: .18,
+		lightness: .55
+	},
+	{
+		name: "cyan",
+		hue: 195,
+		chroma: .18,
+		lightness: .55
+	},
+	{
+		name: "indigo",
+		hue: 265,
+		chroma: .18,
+		lightness: .55
+	}
+];
+/**
+* Look up a preset by name and return its generated palette.
+*
+* @param name - Kebab-case preset name (e.g. 'ocean-blue', 'violet')
+* @returns The full light + dark `ThemePalette` for the preset
+* @throws {Error} If no preset matches the given name
+*/
+function getPreset(name) {
+	const preset = presets.find((p) => p.name === name);
+	if (!preset) throw new Error(`Unknown preset "${name}". Available: ${presets.map((p) => p.name).join(", ")}`);
+	return generatePalette({
+		h: preset.hue,
+		c: preset.chroma,
+		l: preset.lightness
+	});
+}
+
+//#endregion
+//#region src/tokens.ts
+/**
+* Design tokens for @lmring/theme
+*
+* Static design tokens covering spacing, radius, shadow, typography,
+* line-height (leading), easing, and duration values.
+*
+* Spacing uses a 4px base grid. All numeric spacing values (excluding 0)
+* are positive multiples of 4.
+*/
+/** Spacing scale based on 4px grid */
+const spacing = {
+	0: "0px",
+	1: "4px",
+	2: "8px",
+	3: "12px",
+	4: "16px",
+	5: "20px",
+	6: "24px",
+	8: "32px",
+	10: "40px",
+	12: "48px",
+	16: "64px"
+};
+/** Border-radius scale with 10px (0.625rem) base */
+const radius = {
+	sm: "calc(var(--radius) - 4px)",
+	md: "calc(var(--radius) - 2px)",
+	lg: "var(--radius)",
+	xl: "calc(var(--radius) + 4px)",
+	"2xl": "calc(var(--radius) + 8px)",
+	full: "9999px"
+};
+/** Multi-layer composite shadow system (3 levels) */
+const shadow = {
+	sm: "0 1px 2px oklch(0 0 0 / 3%), 0 1px 3px oklch(0 0 0 / 2%)",
+	md: "0 2px 4px oklch(0 0 0 / 3%), 0 4px 8px oklch(0 0 0 / 3%), 0 8px 16px oklch(0 0 0 / 2%)",
+	lg: "0 4px 8px oklch(0 0 0 / 3%), 0 8px 16px oklch(0 0 0 / 3%), 0 16px 32px oklch(0 0 0 / 4%), 0 32px 64px oklch(0 0 0 / 2%)"
+};
+/** Typography font-size scale (rem values) */
+const typography = {
+	xs: "0.75rem",
+	sm: "0.875rem",
+	base: "1rem",
+	lg: "1.125rem",
+	xl: "1.25rem",
+	"2xl": "1.5rem",
+	"3xl": "1.875rem",
+	"4xl": "2.25rem"
+};
+/** Line-height scale */
+const leading = {
+	tight: "1.25",
+	snug: "1.375",
+	normal: "1.5",
+	relaxed: "1.625",
+	loose: "1.75"
+};
+/** CSS easing functions */
+const easing = {
+	spring: "cubic-bezier(0.34, 1.56, 0.64, 1)",
+	smooth: "cubic-bezier(0.25, 0.1, 0.25, 1)",
+	outExpo: "cubic-bezier(0.16, 1, 0.3, 1)"
+};
+/** Animation duration values */
+const duration = {
+	fast: "150ms",
+	normal: "200ms",
+	slow: "300ms",
+	slower: "500ms"
+};
+/** All design tokens grouped by category */
+const tokens = {
+	spacing,
+	radius,
+	shadow,
+	typography,
+	leading,
+	easing,
+	duration
+};
+
+//#endregion
+//#region src/css-generator.ts
+/**
+* CSS variable generator.
+*
+* Converts a SemanticPalette into CSS custom property key-value pairs
+* for injection into the document root element.
+*/
+/**
+* Convert a camelCase string to kebab-case.
+*
+* @example camelToKebab('primaryForeground') // 'primary-foreground'
+*/
+function camelToKebab(str) {
+	return str.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);
+}
+/**
+* Convert a SemanticPalette into a Record of CSS custom properties.
+*
+* Each key in the palette is converted from camelCase to a `--kebab-case`
+* CSS variable name, and each value is formatted as an `oklch(l c h)` string.
+*
+* @param palette - A semantic palette (light or dark)
+* @returns A record mapping CSS variable names to OKLCH CSS values
+*
+* @example
+* paletteToCssVars(palette)
+* // { '--primary': 'oklch(0.55 0.18 255)', '--primary-foreground': 'oklch(1 0 0)', ... }
+*/
+function paletteToCssVars(palette) {
+	const vars = {};
+	for (const [key, color] of Object.entries(palette)) {
+		const cssVarName = `--${camelToKebab(key)}`;
+		vars[cssVarName] = oklchToCss(color);
+	}
+	return vars;
+}
+
+//#endregion
+//#region src/persistence.ts
+const VALID_MODES = new Set([
+	"light",
+	"dark",
+	"system"
+]);
+/** Serialize a theme config to a JSON string. */
+function serialize(config) {
+	return JSON.stringify(config);
+}
+/**
+* Deserialize a raw JSON string into a validated {@link PersistedThemeConfig}.
+*
+* Returns `null` when:
+* - the string is not valid JSON
+* - any field fails validation (mode enum, OKLCH ranges, presetName type)
+*/
+function deserialize(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+	const obj = parsed;
+	if (!VALID_MODES.has(obj.mode)) return null;
+	if (!isValidOklchColor(obj.seedColor)) return null;
+	if (obj.presetName !== null && typeof obj.presetName !== "string") return null;
+	return {
+		mode: obj.mode,
+		seedColor: obj.seedColor,
+		presetName: obj.presetName
+	};
+}
+function isValidOklchColor(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const color = value;
+	return typeof color.l === "number" && typeof color.c === "number" && typeof color.h === "number" && color.l >= 0 && color.l <= 1 && color.c >= 0 && color.c <= .4 && color.h >= 0 && color.h <= 360;
+}
+
+//#endregion
+export { deserialize, generatePalette, getContrastRatio, getPreset, getRelativeLuminance, hexToOklch, meetsWcagAA, mergePalette, oklchToCss, oklchToHex, paletteToCssVars, presets, serialize, tokens };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/color-convert.ts","../src/contrast.ts","../src/color-engine.ts","../src/presets.ts","../src/tokens.ts","../src/css-generator.ts","../src/persistence.ts"],"sourcesContent":["/**\r\n * Color space conversion utilities.\r\n *\r\n * Converts between HEX, OKLCH, and CSS string representations\r\n * using the `culori` library for accurate color math.\r\n */\r\n\r\nimport { converter, formatHex } from 'culori';\r\nimport type { OklchColor } from './types';\r\n\r\nconst toOklch = converter('oklch');\r\n\r\nconst HEX_REGEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;\r\n\r\n/**\r\n * Validate that a string is a valid HEX color (#RGB or #RRGGBB).\r\n * Throws if the format is invalid.\r\n */\r\nfunction assertValidHex(hex: string): void {\r\n  if (!HEX_REGEX.test(hex)) {\r\n    throw new Error(\r\n      `Invalid HEX color: \"${hex}\". Expected format: #RGB or #RRGGBB.`,\r\n    );\r\n  }\r\n}\r\n\r\n/**\r\n * Convert a HEX color string to an OKLCH color object.\r\n *\r\n * @param hex - A valid 3 or 6 digit HEX string with `#` prefix (e.g. `#ff0000`, `#f00`)\r\n * @returns The color in OKLCH space\r\n * @throws If the HEX string is invalid\r\n */\r\nexport function hexToOklch(hex: string): OklchColor {\r\n  assertValidHex(hex);\r\n  const result = toOklch(hex);\r\n  if (!result) {\r\n    throw new Error(`Failed to convert HEX \"${hex}\" to OKLCH.`);\r\n  }\r\n  return {\r\n    l: result.l,\r\n    c: result.c ?? 0,\r\n    h: result.h ?? 0,\r\n  };\r\n}\r\n\r\n/**\r\n * Convert an OKLCH color object back to a 6-digit HEX string.\r\n *\r\n * @param color - An OKLCH color\r\n * @returns A HEX string like `#rrggbb`\r\n */\r\nexport function oklchToHex(color: OklchColor): string {\r\n  const hex = formatHex({ mode: 'oklch', l: color.l, c: color.c, h: color.h });\r\n  return hex;\r\n}\r\n\r\n/**\r\n * Format an OKLCH color as a CSS `oklch()` function string.\r\n *\r\n * @param color - An OKLCH color\r\n * @returns A string like `oklch(0.5 0.2 270)`\r\n */\r\nexport function oklchToCss(color: OklchColor): string {\r\n  return `oklch(${color.l} ${color.c} ${color.h})`;\r\n}\r\n","/**\r\n * WCAG 2.1 contrast ratio utilities.\r\n *\r\n * Computes relative luminance and contrast ratios for OKLCH colors\r\n * by converting through sRGB, following the WCAG 2.1 specification.\r\n */\r\n\r\nimport { converter } from 'culori';\r\nimport type { OklchColor } from './types';\r\n\r\nconst toRgb = converter('rgb');\r\n\r\n/**\r\n * Linearize a single sRGB channel value for luminance calculation.\r\n *\r\n * @param c - sRGB channel value in [0, 1]\r\n * @returns Linear RGB value\r\n */\r\nfunction linearize(c: number): number {\r\n  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;\r\n}\r\n\r\n/**\r\n * Compute the WCAG 2.1 relative luminance of an OKLCH color.\r\n *\r\n * Converts the color to sRGB, linearizes each channel, then applies\r\n * the standard luminance coefficients: 0.2126·R + 0.7152·G + 0.0722·B.\r\n *\r\n * @param color - An OKLCH color\r\n * @returns Relative luminance in [0, 1]\r\n */\r\nexport function getRelativeLuminance(color: OklchColor): number {\r\n  const rgb = toRgb({ mode: 'oklch', l: color.l, c: color.c, h: color.h });\r\n  if (!rgb) {\r\n    return 0;\r\n  }\r\n\r\n  const r = linearize(Math.max(0, Math.min(1, rgb.r)));\r\n  const g = linearize(Math.max(0, Math.min(1, rgb.g)));\r\n  const b = linearize(Math.max(0, Math.min(1, rgb.b)));\r\n\r\n  return 0.2126 * r + 0.7152 * g + 0.0722 * b;\r\n}\r\n\r\n/**\r\n * Compute the WCAG 2.1 contrast ratio between two OKLCH colors.\r\n *\r\n * The ratio is always ≥ 1, with 21:1 being the maximum (black on white).\r\n *\r\n * @param fg - Foreground color\r\n * @param bg - Background color\r\n * @returns Contrast ratio (e.g. 4.5 means 4.5:1)\r\n */\r\nexport function getContrastRatio(fg: OklchColor, bg: OklchColor): number {\r\n  const l1 = getRelativeLuminance(fg);\r\n  const l2 = getRelativeLuminance(bg);\r\n  const lighter = Math.max(l1, l2);\r\n  const darker = Math.min(l1, l2);\r\n  return (lighter + 0.05) / (darker + 0.05);\r\n}\r\n\r\n/**\r\n * Check whether two OKLCH colors meet the WCAG 2.1 AA contrast requirement.\r\n *\r\n * - Normal text: contrast ratio ≥ 4.5:1\r\n * - Large text (≥ 18pt or ≥ 14pt bold): contrast ratio ≥ 3.0:1\r\n *\r\n * @param fg - Foreground color\r\n * @param bg - Background color\r\n * @param isLargeText - Whether the text qualifies as \"large\" under WCAG\r\n * @returns `true` if the pair meets WCAG AA\r\n */\r\nexport function meetsWcagAA(\r\n  fg: OklchColor,\r\n  bg: OklchColor,\r\n  isLargeText: boolean,\r\n): boolean {\r\n  const ratio = getContrastRatio(fg, bg);\r\n  return isLargeText ? ratio >= 3.0 : ratio >= 4.5;\r\n}\r\n","/**\r\n * OKLCH palette generation engine.\r\n *\r\n * Given a seed color in OKLCH space, generates a complete semantic palette\r\n * for both light and dark modes following the design system's generation rules.\r\n */\r\n\r\nimport type { OklchColor, SemanticPalette, ThemePalette } from './types';\r\n\r\n/**\r\n * Clamp a number to the given range.\r\n */\r\nfunction clamp(value: number, min: number, max: number): number {\r\n  return Math.min(max, Math.max(min, value));\r\n}\r\n\r\n/**\r\n * Normalize a hue value to [0, 360).\r\n */\r\nfunction normalizeHue(h: number): number {\r\n  return ((h % 360) + 360) % 360;\r\n}\r\n\r\n/**\r\n * Create a valid OklchColor with clamped values.\r\n */\r\nfunction oklch(l: number, c: number, h: number): OklchColor {\r\n  return {\r\n    l: clamp(l, 0, 1),\r\n    c: clamp(c, 0, 0.4),\r\n    h: normalizeHue(h),\r\n  };\r\n}\r\n\r\n/**\r\n * Derive the light-mode semantic palette from a seed color.\r\n */\r\nfunction generateLightPalette(seed: OklchColor): SemanticPalette {\r\n  const h = normalizeHue(seed.h);\r\n\r\n  const primary = oklch(0.52, seed.c, h);\r\n\r\n  return {\r\n    primary,\r\n    primaryForeground: oklch(1.0, 0, h),\r\n    secondary: oklch(0.96, 0.005, h),\r\n    secondaryForeground: oklch(0.25, 0.015, h),\r\n    accent: oklch(0.96, 0.01, h),\r\n    accentForeground: oklch(0.25, 0.015, h),\r\n    muted: oklch(0.96, 0.005, h),\r\n    mutedForeground: oklch(0.58, 0.01, h),\r\n    destructive: oklch(0.55, 0.22, 25),\r\n    destructiveForeground: oklch(1.0, 0, 25),\r\n    background: oklch(0.98, 0.002, h),\r\n    foreground: oklch(0.20, 0.015, h),\r\n    card: oklch(1.0, 0, h),\r\n    cardForeground: oklch(0.20, 0.015, h),\r\n    border: oklch(0.90, 0.005, h),\r\n    input: oklch(0.95, 0.005, h),\r\n    ring: primary,\r\n  };\r\n}\r\n\r\n/**\r\n * Derive the dark-mode semantic palette from a seed color.\r\n *\r\n * Uses a layered surface system with increasing lightness:\r\n *   Layer 0 (background): L=0.14\r\n *   Layer 1 (card):       L=0.18\r\n *   Layer 2 (elevated):   L=0.22  (mapped to `input`)\r\n *   Layer 3 (overlay):    L=0.26  (mapped to `border` at L=0.28 per rules table)\r\n */\r\nfunction generateDarkPalette(seed: OklchColor): SemanticPalette {\r\n  const h = normalizeHue(seed.h);\r\n\r\n  const primary = oklch(0.45, seed.c * 0.9, h);\r\n\r\n  return {\r\n    primary,\r\n    primaryForeground: oklch(0.98, 0.005, h),\r\n    secondary: oklch(0.25, 0.01, h),\r\n    secondaryForeground: oklch(0.90, 0.005, h),\r\n    accent: oklch(0.28, 0.015, h),\r\n    accentForeground: oklch(0.90, 0.005, h),\r\n    muted: oklch(0.25, 0.01, h),\r\n    mutedForeground: oklch(0.72, 0.005, h),\r\n    destructive: oklch(0.60, 0.24, 25),\r\n    destructiveForeground: oklch(0.95, 0.01, 25),\r\n    background: oklch(0.14, 0.01, h),\r\n    foreground: oklch(0.95, 0.005, h),\r\n    card: oklch(0.18, 0.01, h),\r\n    cardForeground: oklch(0.95, 0.005, h),\r\n    border: oklch(0.28, 0.01, h),\r\n    input: oklch(0.22, 0.01, h),\r\n    ring: primary,\r\n  };\r\n}\r\n\r\n\r\n/**\r\n * Generate a complete light + dark semantic palette from a seed OKLCH color.\r\n *\r\n * The seed color's hue drives the entire palette. Lightness and chroma\r\n * are adjusted per semantic role according to the design system rules.\r\n *\r\n * @param seed - The user-chosen seed color in OKLCH space\r\n * @returns A `ThemePalette` with `light` and `dark` semantic palettes\r\n */\r\nexport function generatePalette(seed: OklchColor): ThemePalette {\r\n  return {\r\n    light: generateLightPalette(seed),\r\n    dark: generateDarkPalette(seed),\r\n  };\r\n}\r\n\r\n/**\r\n * Deep-merge partial overrides into a base palette.\r\n *\r\n * Overridden keys take the override value; all other keys are preserved\r\n * from the base. Always returns a new object (no mutation).\r\n *\r\n * @param base - The base palette to start from\r\n * @param overrides - Partial light/dark overrides to apply\r\n * @returns A new `ThemePalette` with overrides merged in\r\n */\r\nexport function mergePalette(\r\n  base: ThemePalette,\r\n  overrides: Partial<{\r\n    light: Partial<SemanticPalette>;\r\n    dark: Partial<SemanticPalette>;\r\n  }>,\r\n): ThemePalette {\r\n  return {\r\n    light: { ...base.light, ...overrides.light },\r\n    dark: { ...base.dark, ...overrides.dark },\r\n  };\r\n}\r\n","/**\r\n * Preset theme definitions for @lmring/theme.\r\n *\r\n * Each preset is defined by its OKLCH hue angle. The color engine\r\n * generates a full semantic palette from the seed parameters.\r\n */\r\n\r\nimport { generatePalette } from './color-engine';\r\nimport type { ThemePalette, ThemePreset } from './types';\r\n\r\n/**\r\n * All available preset themes.\r\n *\r\n * Each preset uses a default chroma of 0.18 and lightness of 0.55,\r\n * varying only in hue to produce distinct color families.\r\n */\r\nexport const presets: ThemePreset[] = [\r\n  { name: 'ocean-blue', hue: 255, chroma: 0.18, lightness: 0.55 },\r\n  { name: 'violet', hue: 280, chroma: 0.18, lightness: 0.55 },\r\n  { name: 'emerald', hue: 155, chroma: 0.18, lightness: 0.55 },\r\n  { name: 'amber', hue: 75, chroma: 0.18, lightness: 0.55 },\r\n  { name: 'rose', hue: 350, chroma: 0.18, lightness: 0.55 },\r\n  { name: 'crimson', hue: 25, chroma: 0.18, lightness: 0.55 },\r\n  { name: 'cyan', hue: 195, chroma: 0.18, lightness: 0.55 },\r\n  { name: 'indigo', hue: 265, chroma: 0.18, lightness: 0.55 },\r\n];\r\n\r\n/**\r\n * Look up a preset by name and return its generated palette.\r\n *\r\n * @param name - Kebab-case preset name (e.g. 'ocean-blue', 'violet')\r\n * @returns The full light + dark `ThemePalette` for the preset\r\n * @throws {Error} If no preset matches the given name\r\n */\r\nexport function getPreset(name: string): ThemePalette {\r\n  const preset = presets.find((p) => p.name === name);\r\n  if (!preset) {\r\n    throw new Error(\r\n      `Unknown preset \"${name}\". Available: ${presets.map((p) => p.name).join(', ')}`,\r\n    );\r\n  }\r\n  return generatePalette({ h: preset.hue, c: preset.chroma, l: preset.lightness });\r\n}\r\n","/**\r\n * Design tokens for @lmring/theme\r\n *\r\n * Static design tokens covering spacing, radius, shadow, typography,\r\n * line-height (leading), easing, and duration values.\r\n *\r\n * Spacing uses a 4px base grid. All numeric spacing values (excluding 0)\r\n * are positive multiples of 4.\r\n */\r\n\r\n/** Spacing scale based on 4px grid */\r\nconst spacing = {\r\n  0: '0px',\r\n  1: '4px',\r\n  2: '8px',\r\n  3: '12px',\r\n  4: '16px',\r\n  5: '20px',\r\n  6: '24px',\r\n  8: '32px',\r\n  10: '40px',\r\n  12: '48px',\r\n  16: '64px',\r\n} as const;\r\n\r\n/** Border-radius scale with 10px (0.625rem) base */\r\nconst radius = {\r\n  sm: 'calc(var(--radius) - 4px)',\r\n  md: 'calc(var(--radius) - 2px)',\r\n  lg: 'var(--radius)',\r\n  xl: 'calc(var(--radius) + 4px)',\r\n  '2xl': 'calc(var(--radius) + 8px)',\r\n  full: '9999px',\r\n} as const;\r\n\r\n/** Multi-layer composite shadow system (3 levels) */\r\nconst shadow = {\r\n  sm: '0 1px 2px oklch(0 0 0 / 3%), 0 1px 3px oklch(0 0 0 / 2%)',\r\n  md: '0 2px 4px oklch(0 0 0 / 3%), 0 4px 8px oklch(0 0 0 / 3%), 0 8px 16px oklch(0 0 0 / 2%)',\r\n  lg: '0 4px 8px oklch(0 0 0 / 3%), 0 8px 16px oklch(0 0 0 / 3%), 0 16px 32px oklch(0 0 0 / 4%), 0 32px 64px oklch(0 0 0 / 2%)',\r\n} as const;\r\n\r\n/** Typography font-size scale (rem values) */\r\nconst typography = {\r\n  xs: '0.75rem',\r\n  sm: '0.875rem',\r\n  base: '1rem',\r\n  lg: '1.125rem',\r\n  xl: '1.25rem',\r\n  '2xl': '1.5rem',\r\n  '3xl': '1.875rem',\r\n  '4xl': '2.25rem',\r\n} as const;\r\n\r\n/** Line-height scale */\r\nconst leading = {\r\n  tight: '1.25',\r\n  snug: '1.375',\r\n  normal: '1.5',\r\n  relaxed: '1.625',\r\n  loose: '1.75',\r\n} as const;\r\n\r\n/** CSS easing functions */\r\nconst easing = {\r\n  spring: 'cubic-bezier(0.34, 1.56, 0.64, 1)',\r\n  smooth: 'cubic-bezier(0.25, 0.1, 0.25, 1)',\r\n  outExpo: 'cubic-bezier(0.16, 1, 0.3, 1)',\r\n} as const;\r\n\r\n/** Animation duration values */\r\nconst duration = {\r\n  fast: '150ms',\r\n  normal: '200ms',\r\n  slow: '300ms',\r\n  slower: '500ms',\r\n} as const;\r\n\r\n/** All design tokens grouped by category */\r\nexport const tokens = {\r\n  spacing,\r\n  radius,\r\n  shadow,\r\n  typography,\r\n  leading,\r\n  easing,\r\n  duration,\r\n} as const;\r\n","/**\r\n * CSS variable generator.\r\n *\r\n * Converts a SemanticPalette into CSS custom property key-value pairs\r\n * for injection into the document root element.\r\n */\r\n\r\nimport { oklchToCss } from './color-convert';\r\nimport type { SemanticPalette } from './types';\r\n\r\n/**\r\n * Convert a camelCase string to kebab-case.\r\n *\r\n * @example camelToKebab('primaryForeground') // 'primary-foreground'\r\n */\r\nfunction camelToKebab(str: string): string {\r\n  return str.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);\r\n}\r\n\r\n/**\r\n * Convert a SemanticPalette into a Record of CSS custom properties.\r\n *\r\n * Each key in the palette is converted from camelCase to a `--kebab-case`\r\n * CSS variable name, and each value is formatted as an `oklch(l c h)` string.\r\n *\r\n * @param palette - A semantic palette (light or dark)\r\n * @returns A record mapping CSS variable names to OKLCH CSS values\r\n *\r\n * @example\r\n * paletteToCssVars(palette)\r\n * // { '--primary': 'oklch(0.55 0.18 255)', '--primary-foreground': 'oklch(1 0 0)', ... }\r\n */\r\nexport function paletteToCssVars(palette: SemanticPalette): Record<string, string> {\r\n  const vars: Record<string, string> = {};\r\n\r\n  for (const [key, color] of Object.entries(palette)) {\r\n    const cssVarName = `--${camelToKebab(key)}`;\r\n    vars[cssVarName] = oklchToCss(color);\r\n  }\r\n\r\n  return vars;\r\n}\r\n","/**\r\n * Theme configuration serialization and deserialization.\r\n *\r\n * Provides pure-function helpers for persisting a {@link PersistedThemeConfig}\r\n * to/from JSON strings. Deserialization includes full validation so callers\r\n * can safely trust the returned value.\r\n */\r\n\r\nimport type { PersistedThemeConfig, OklchColor } from './types';\r\n\r\nconst VALID_MODES = new Set<PersistedThemeConfig['mode']>([\r\n  'light',\r\n  'dark',\r\n  'system',\r\n]);\r\n\r\n/** Serialize a theme config to a JSON string. */\r\nexport function serialize(config: PersistedThemeConfig): string {\r\n  return JSON.stringify(config);\r\n}\r\n\r\n/**\r\n * Deserialize a raw JSON string into a validated {@link PersistedThemeConfig}.\r\n *\r\n * Returns `null` when:\r\n * - the string is not valid JSON\r\n * - any field fails validation (mode enum, OKLCH ranges, presetName type)\r\n */\r\nexport function deserialize(raw: string): PersistedThemeConfig | null {\r\n  let parsed: unknown;\r\n  try {\r\n    parsed = JSON.parse(raw);\r\n  } catch {\r\n    return null;\r\n  }\r\n\r\n  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {\r\n    return null;\r\n  }\r\n\r\n  const obj = parsed as Record<string, unknown>;\r\n\r\n  // Validate mode\r\n  if (!VALID_MODES.has(obj.mode as PersistedThemeConfig['mode'])) {\r\n    return null;\r\n  }\r\n\r\n  // Validate seedColor\r\n  if (!isValidOklchColor(obj.seedColor)) {\r\n    return null;\r\n  }\r\n\r\n  // Validate presetName\r\n  if (obj.presetName !== null && typeof obj.presetName !== 'string') {\r\n    return null;\r\n  }\r\n\r\n  return {\r\n    mode: obj.mode as PersistedThemeConfig['mode'],\r\n    seedColor: obj.seedColor as OklchColor,\r\n    presetName: obj.presetName as string | null,\r\n  };\r\n}\r\n\r\nfunction isValidOklchColor(value: unknown): value is OklchColor {\r\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) {\r\n    return false;\r\n  }\r\n\r\n  const color = value as Record<string, unknown>;\r\n\r\n  return (\r\n    typeof color.l === 'number' &&\r\n    typeof color.c === 'number' &&\r\n    typeof color.h === 'number' &&\r\n    color.l >= 0 &&\r\n    color.l <= 1 &&\r\n    color.c >= 0 &&\r\n    color.c <= 0.4 &&\r\n    color.h >= 0 &&\r\n    color.h <= 360\r\n  );\r\n}\r\n"],"mappings":";;;;;;;;;AAUA,MAAM,UAAU,UAAU,QAAQ;AAElC,MAAM,YAAY;;;;;AAMlB,SAAS,eAAe,KAAmB;AACzC,KAAI,CAAC,UAAU,KAAK,IAAI,CACtB,OAAM,IAAI,MACR,uBAAuB,IAAI,sCAC5B;;;;;;;;;AAWL,SAAgB,WAAW,KAAyB;AAClD,gBAAe,IAAI;CACnB,MAAM,SAAS,QAAQ,IAAI;AAC3B,KAAI,CAAC,OACH,OAAM,IAAI,MAAM,0BAA0B,IAAI,aAAa;AAE7D,QAAO;EACL,GAAG,OAAO;EACV,GAAG,OAAO,KAAK;EACf,GAAG,OAAO,KAAK;EAChB;;;;;;;;AASH,SAAgB,WAAW,OAA2B;AAEpD,QADY,UAAU;EAAE,MAAM;EAAS,GAAG,MAAM;EAAG,GAAG,MAAM;EAAG,GAAG,MAAM;EAAG,CAAC;;;;;;;;AAU9E,SAAgB,WAAW,OAA2B;AACpD,QAAO,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE;;;;;;;;;;;ACtDhD,MAAM,QAAQ,UAAU,MAAM;;;;;;;AAQ9B,SAAS,UAAU,GAAmB;AACpC,QAAO,KAAK,SAAU,IAAI,UAAU,IAAI,QAAS,UAAU;;;;;;;;;;;AAY7D,SAAgB,qBAAqB,OAA2B;CAC9D,MAAM,MAAM,MAAM;EAAE,MAAM;EAAS,GAAG,MAAM;EAAG,GAAG,MAAM;EAAG,GAAG,MAAM;EAAG,CAAC;AACxE,KAAI,CAAC,IACH,QAAO;CAGT,MAAM,IAAI,UAAU,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,IAAI,EAAE,CAAC,CAAC;CACpD,MAAM,IAAI,UAAU,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,IAAI,EAAE,CAAC,CAAC;CACpD,MAAM,IAAI,UAAU,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,IAAI,EAAE,CAAC,CAAC;AAEpD,QAAO,QAAS,IAAI,QAAS,IAAI,QAAS;;;;;;;;;;;AAY5C,SAAgB,iBAAiB,IAAgB,IAAwB;CACvE,MAAM,KAAK,qBAAqB,GAAG;CACnC,MAAM,KAAK,qBAAqB,GAAG;CACnC,MAAM,UAAU,KAAK,IAAI,IAAI,GAAG;CAChC,MAAM,SAAS,KAAK,IAAI,IAAI,GAAG;AAC/B,SAAQ,UAAU,QAAS,SAAS;;;;;;;;;;;;;AActC,SAAgB,YACd,IACA,IACA,aACS;CACT,MAAM,QAAQ,iBAAiB,IAAI,GAAG;AACtC,QAAO,cAAc,SAAS,IAAM,SAAS;;;;;;;;AClE/C,SAAS,MAAM,OAAe,KAAa,KAAqB;AAC9D,QAAO,KAAK,IAAI,KAAK,KAAK,IAAI,KAAK,MAAM,CAAC;;;;;AAM5C,SAAS,aAAa,GAAmB;AACvC,SAAS,IAAI,MAAO,OAAO;;;;;AAM7B,SAAS,MAAM,GAAW,GAAW,GAAuB;AAC1D,QAAO;EACL,GAAG,MAAM,GAAG,GAAG,EAAE;EACjB,GAAG,MAAM,GAAG,GAAG,GAAI;EACnB,GAAG,aAAa,EAAE;EACnB;;;;;AAMH,SAAS,qBAAqB,MAAmC;CAC/D,MAAM,IAAI,aAAa,KAAK,EAAE;CAE9B,MAAM,UAAU,MAAM,KAAM,KAAK,GAAG,EAAE;AAEtC,QAAO;EACL;EACA,mBAAmB,MAAM,GAAK,GAAG,EAAE;EACnC,WAAW,MAAM,KAAM,MAAO,EAAE;EAChC,qBAAqB,MAAM,KAAM,MAAO,EAAE;EAC1C,QAAQ,MAAM,KAAM,KAAM,EAAE;EAC5B,kBAAkB,MAAM,KAAM,MAAO,EAAE;EACvC,OAAO,MAAM,KAAM,MAAO,EAAE;EAC5B,iBAAiB,MAAM,KAAM,KAAM,EAAE;EACrC,aAAa,MAAM,KAAM,KAAM,GAAG;EAClC,uBAAuB,MAAM,GAAK,GAAG,GAAG;EACxC,YAAY,MAAM,KAAM,MAAO,EAAE;EACjC,YAAY,MAAM,IAAM,MAAO,EAAE;EACjC,MAAM,MAAM,GAAK,GAAG,EAAE;EACtB,gBAAgB,MAAM,IAAM,MAAO,EAAE;EACrC,QAAQ,MAAM,IAAM,MAAO,EAAE;EAC7B,OAAO,MAAM,KAAM,MAAO,EAAE;EAC5B,MAAM;EACP;;;;;;;;;;;AAYH,SAAS,oBAAoB,MAAmC;CAC9D,MAAM,IAAI,aAAa,KAAK,EAAE;CAE9B,MAAM,UAAU,MAAM,KAAM,KAAK,IAAI,IAAK,EAAE;AAE5C,QAAO;EACL;EACA,mBAAmB,MAAM,KAAM,MAAO,EAAE;EACxC,WAAW,MAAM,KAAM,KAAM,EAAE;EAC/B,qBAAqB,MAAM,IAAM,MAAO,EAAE;EAC1C,QAAQ,MAAM,KAAM,MAAO,EAAE;EAC7B,kBAAkB,MAAM,IAAM,MAAO,EAAE;EACvC,OAAO,MAAM,KAAM,KAAM,EAAE;EAC3B,iBAAiB,MAAM,KAAM,MAAO,EAAE;EACtC,aAAa,MAAM,IAAM,KAAM,GAAG;EAClC,uBAAuB,MAAM,KAAM,KAAM,GAAG;EAC5C,YAAY,MAAM,KAAM,KAAM,EAAE;EAChC,YAAY,MAAM,KAAM,MAAO,EAAE;EACjC,MAAM,MAAM,KAAM,KAAM,EAAE;EAC1B,gBAAgB,MAAM,KAAM,MAAO,EAAE;EACrC,QAAQ,MAAM,KAAM,KAAM,EAAE;EAC5B,OAAO,MAAM,KAAM,KAAM,EAAE;EAC3B,MAAM;EACP;;;;;;;;;;;AAaH,SAAgB,gBAAgB,MAAgC;AAC9D,QAAO;EACL,OAAO,qBAAqB,KAAK;EACjC,MAAM,oBAAoB,KAAK;EAChC;;;;;;;;;;;;AAaH,SAAgB,aACd,MACA,WAIc;AACd,QAAO;EACL,OAAO;GAAE,GAAG,KAAK;GAAO,GAAG,UAAU;GAAO;EAC5C,MAAM;GAAE,GAAG,KAAK;GAAM,GAAG,UAAU;GAAM;EAC1C;;;;;;;;;;;;;;;;;ACvHH,MAAa,UAAyB;CACpC;EAAE,MAAM;EAAc,KAAK;EAAK,QAAQ;EAAM,WAAW;EAAM;CAC/D;EAAE,MAAM;EAAU,KAAK;EAAK,QAAQ;EAAM,WAAW;EAAM;CAC3D;EAAE,MAAM;EAAW,KAAK;EAAK,QAAQ;EAAM,WAAW;EAAM;CAC5D;EAAE,MAAM;EAAS,KAAK;EAAI,QAAQ;EAAM,WAAW;EAAM;CACzD;EAAE,MAAM;EAAQ,KAAK;EAAK,QAAQ;EAAM,WAAW;EAAM;CACzD;EAAE,MAAM;EAAW,KAAK;EAAI,QAAQ;EAAM,WAAW;EAAM;CAC3D;EAAE,MAAM;EAAQ,KAAK;EAAK,QAAQ;EAAM,WAAW;EAAM;CACzD;EAAE,MAAM;EAAU,KAAK;EAAK,QAAQ;EAAM,WAAW;EAAM;CAC5D;;;;;;;;AASD,SAAgB,UAAU,MAA4B;CACpD,MAAM,SAAS,QAAQ,MAAM,MAAM,EAAE,SAAS,KAAK;AACnD,KAAI,CAAC,OACH,OAAM,IAAI,MACR,mBAAmB,KAAK,gBAAgB,QAAQ,KAAK,MAAM,EAAE,KAAK,CAAC,KAAK,KAAK,GAC9E;AAEH,QAAO,gBAAgB;EAAE,GAAG,OAAO;EAAK,GAAG,OAAO;EAAQ,GAAG,OAAO;EAAW,CAAC;;;;;;;;;;;;;;;AC9BlF,MAAM,UAAU;CACd,GAAG;CACH,GAAG;CACH,GAAG;CACH,GAAG;CACH,GAAG;CACH,GAAG;CACH,GAAG;CACH,GAAG;CACH,IAAI;CACJ,IAAI;CACJ,IAAI;CACL;;AAGD,MAAM,SAAS;CACb,IAAI;CACJ,IAAI;CACJ,IAAI;CACJ,IAAI;CACJ,OAAO;CACP,MAAM;CACP;;AAGD,MAAM,SAAS;CACb,IAAI;CACJ,IAAI;CACJ,IAAI;CACL;;AAGD,MAAM,aAAa;CACjB,IAAI;CACJ,IAAI;CACJ,MAAM;CACN,IAAI;CACJ,IAAI;CACJ,OAAO;CACP,OAAO;CACP,OAAO;CACR;;AAGD,MAAM,UAAU;CACd,OAAO;CACP,MAAM;CACN,QAAQ;CACR,SAAS;CACT,OAAO;CACR;;AAGD,MAAM,SAAS;CACb,QAAQ;CACR,QAAQ;CACR,SAAS;CACV;;AAGD,MAAM,WAAW;CACf,MAAM;CACN,QAAQ;CACR,MAAM;CACN,QAAQ;CACT;;AAGD,MAAa,SAAS;CACpB;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;;;;;;;;ACxED,SAAS,aAAa,KAAqB;AACzC,QAAO,IAAI,QAAQ,WAAW,UAAU,IAAI,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;AAgBpE,SAAgB,iBAAiB,SAAkD;CACjF,MAAM,OAA+B,EAAE;AAEvC,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,QAAQ,EAAE;EAClD,MAAM,aAAa,KAAK,aAAa,IAAI;AACzC,OAAK,cAAc,WAAW,MAAM;;AAGtC,QAAO;;;;;AC9BT,MAAM,cAAc,IAAI,IAAkC;CACxD;CACA;CACA;CACD,CAAC;;AAGF,SAAgB,UAAU,QAAsC;AAC9D,QAAO,KAAK,UAAU,OAAO;;;;;;;;;AAU/B,SAAgB,YAAY,KAA0C;CACpE,IAAI;AACJ,KAAI;AACF,WAAS,KAAK,MAAM,IAAI;SAClB;AACN,SAAO;;AAGT,KAAI,OAAO,WAAW,YAAY,WAAW,QAAQ,MAAM,QAAQ,OAAO,CACxE,QAAO;CAGT,MAAM,MAAM;AAGZ,KAAI,CAAC,YAAY,IAAI,IAAI,KAAqC,CAC5D,QAAO;AAIT,KAAI,CAAC,kBAAkB,IAAI,UAAU,CACnC,QAAO;AAIT,KAAI,IAAI,eAAe,QAAQ,OAAO,IAAI,eAAe,SACvD,QAAO;AAGT,QAAO;EACL,MAAM,IAAI;EACV,WAAW,IAAI;EACf,YAAY,IAAI;EACjB;;AAGH,SAAS,kBAAkB,OAAqC;AAC9D,KAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,MAAM,CACrE,QAAO;CAGT,MAAM,QAAQ;AAEd,QACE,OAAO,MAAM,MAAM,YACnB,OAAO,MAAM,MAAM,YACnB,OAAO,MAAM,MAAM,YACnB,MAAM,KAAK,KACX,MAAM,KAAK,KACX,MAAM,KAAK,KACX,MAAM,KAAK,MACX,MAAM,KAAK,KACX,MAAM,KAAK"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@lmring/theme",
+  "version": "1.0.0",
+  "description": "LMRing theme engine, tokens, presets, and CSS variable generation utilities.",
+  "license": "Apache-2.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./css": "./src/theme.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src/theme.css",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/llm-ring/lmring.git",
+    "directory": "packages/theme"
+  },
+  "homepage": "https://github.com/llm-ring/lmring/tree/main/packages/theme",
+  "bugs": {
+    "url": "https://github.com/llm-ring/lmring/issues"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "culori": "^4.0.1"
+  },
+  "devDependencies": {
+    "@lmring/typescript-config": "workspace:*",
+    "@lmring/vitest-config": "workspace:*",
+    "@vitest/coverage-v8": "^4.1.0",
+    "fast-check": "^4.6.0",
+    "tsdown": "0.21.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}

package/src/theme.css

@@ -0,0 +1,89 @@
+/* @lmring/theme static design tokens. */
+
+@theme {
+  /* Spacing scale (4px grid). */
+  --spacing-0: 0px;
+  --spacing-1: 4px;
+  --spacing-2: 8px;
+  --spacing-3: 12px;
+  --spacing-4: 16px;
+  --spacing-5: 20px;
+  --spacing-6: 24px;
+  --spacing-8: 32px;
+  --spacing-10: 40px;
+  --spacing-12: 48px;
+  --spacing-16: 64px;
+
+  /* Radius scale. */
+  --radius: 0.625rem;
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --radius-2xl: calc(var(--radius) + 8px);
+
+  /* Shadow levels. */
+  --shadow-sm: 0 1px 2px oklch(0 0 0 / 3%), 0 1px 3px oklch(0 0 0 / 2%);
+  --shadow-md:
+    0 2px 4px oklch(0 0 0 / 3%),
+    0 4px 8px oklch(0 0 0 / 3%),
+    0 8px 16px oklch(0 0 0 / 2%);
+  --shadow-lg:
+    0 4px 8px oklch(0 0 0 / 3%),
+    0 8px 16px oklch(0 0 0 / 3%),
+    0 16px 32px oklch(0 0 0 / 4%),
+    0 32px 64px oklch(0 0 0 / 2%);
+
+  /* Typography scale. */
+  --text-xs: 0.75rem;
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.25rem;
+  --text-2xl: 1.5rem;
+  --text-3xl: 1.875rem;
+  --text-4xl: 2.25rem;
+
+  /* Line-height scale. */
+  --leading-tight: 1.25;
+  --leading-snug: 1.375;
+  --leading-normal: 1.5;
+  --leading-relaxed: 1.625;
+  --leading-loose: 1.75;
+
+  /* Motion tokens. */
+  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+  --ease-smooth: cubic-bezier(0.25, 0.1, 0.25, 1);
+  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
+
+  --duration-fast: 150ms;
+  --duration-normal: 200ms;
+  --duration-slow: 300ms;
+  --duration-slower: 500ms;
+}
+
+:root {
+  /* Surface layer tokens for light mode. */
+  --surface: oklch(1 0 0);
+  --elevated: oklch(0.99 0.002 264);
+  --overlay: oklch(0.97 0.005 264);
+}
+
+.dark {
+  /* Surface layer tokens for dark mode. */
+  --surface: oklch(0.18 0.01 264);
+  --elevated: oklch(0.22 0.01 264);
+  --overlay: oklch(0.28 0.01 264);
+
+  /* Dark-mode shadow variants. */
+  --shadow-sm: 0 1px 2px oklch(0 0 0 / 20%), 0 1px 3px oklch(0 0 0 / 15%);
+  --shadow-md:
+    0 2px 4px oklch(0 0 0 / 24%),
+    0 4px 8px oklch(0 0 0 / 20%),
+    0 8px 16px oklch(0 0 0 / 16%);
+  --shadow-lg:
+    0 4px 8px oklch(0 0 0 / 28%),
+    0 8px 16px oklch(0 0 0 / 24%),
+    0 16px 32px oklch(0 0 0 / 20%),
+    0 32px 64px oklch(0 0 0 / 16%);
+}