@rokkit/core 1.0.3 → 1.0.5

package/dist/color-space.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Abstract base class for color space adapters.
+ */
+export class ColorSpace {
+    /**
+     * Factory method to create a ColorSpace adapter by name.
+     * @param {string} space - 'rgb', 'hsl', or 'oklch'
+     * @returns {ColorSpace}
+     */
+    static create(space: string): ColorSpace;
+    /** @returns {string} */
+    get name(): string;
+    /** @returns {string} CSS color-mix interpolation space */
+    get mixSpace(): string;
+    /** @returns {string} CSS function name */
+    get fn(): string;
+    /**
+     * Convert a hex color to bare channels in this space.
+     * @param {string} hex - #rrggbb
+     * @returns {string}
+     */
+    fromHex(_hex: any): string;
+    /**
+     * Wrap any input into a complete CSS color value.
+     * - hex → convert and wrap
+     * - bare channels → wrap in fn()
+     * - already wrapped → pass through
+     * - non-string / null / undefined → pass through
+     * - named colors → pass through
+     * @param {*} value
+     * @returns {*}
+     */
+    wrap(_value: any): any;
+    /**
+     * Produce a color-mix expression for theme CSS variables with alpha support.
+     * @param {string} varName - CSS variable name (e.g. '--color-primary-500')
+     * @returns {string}
+     */
+    themeColor(varName: string): string;
+}
+export class RgbColorSpace extends ColorSpace {
+    fromHex(hex: any): string;
+    wrap(value: any): any;
+}
+export class HslColorSpace extends ColorSpace {
+    fromHex(hex: any): string;
+    wrap(value: any): any;
+}
+export class OklchColorSpace extends ColorSpace {
+    fromHex(hex: any): string;
+    wrap(value: any): any;
+}

package/dist/constants.d.ts

@@ -54,8 +54,10 @@ export namespace DEFAULT_KEYMAP {
 }
 export namespace DEFAULT_THEME_MAPPING {
     let surface: string;
+    let ink: string;
     let primary: string;
     let secondary: string;
+    let tertiary: string;
     let accent: string;
     let success: string;
     let warning: string;
@@ -76,5 +78,6 @@ export namespace TONE_MAP {
     let z9: number;
     let z10: number;
 }
+export const INVERTED_ROLES: Set<string>;
 export const DEFAULT_STATE_ICONS: any;
 export { defaultColors, syntaxColors, shades, defaultPalette } from "./colors/index";

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from "./utils.js";
 export * from "./nested.js";
 export * from "./string.js";
 export * from "./theme.js";
+export { ColorSpace } from "./color-space.js";
 export { FieldMapper } from "./field-mapper.js";
 export { createEmitter } from "./events.js";
 export { getLineTypes } from "./connector.js";

package/dist/theme.d.ts

@@ -1,31 +1,34 @@
 /**
- * Generate shades for a color using css varuable
+ * Generate shades for a color using css variable and a ColorSpace adapter.
  *
  * @param {string} name
- * @param {string} modifier
- * @returns
+ * @param {string|import('./color-space').ColorSpace} space - color space name or adapter instance
+ * @returns {Record<string|number, string>}
  */
-export declare function shadesOf(name: any, modifier?: string): {
-    DEFAULT: any;
+export declare function shadesOf(name: any, space?: string): {
+    DEFAULT: string;
 };
 /**
  * Constructs and returns the light and dark theme variants based on provided color mapping and color definitions.
  *
  * @param {Object} [mapping=DEFAULT_THEME_MAPPING] - An object mapping variant names to color property names.
  * @param {Object} [colors=defaultColors]        - The object containing default color definitions.
+ * @param {string} [colorSpace] - Color space name for CSS variable values.
  * @returns {Array<Array>} An array containing two arrays, one for the light theme variant and another for the dark theme.
  */
-export declare function themeRules(mapping?: {
+export declare function themeRules(mapping: {
     surface: string;
+    ink: string;
     primary: string;
     secondary: string;
+    tertiary: string;
     accent: string;
     success: string;
     warning: string;
     danger: string;
     error: string;
     info: string;
-}, colors?: any): {};
+} | undefined, colors: any, colorSpace: any): {};
 /**
  * Generates UnoCSS shortcut definitions for semantic tones with bg, border, text.
  * @param {string} name - Color name (e.g., 'primary')
@@ -49,14 +52,16 @@ export declare class Theme {
     #private;
     /**
      *
-     * @param {import('./types.js').ColorTheme} param0
+     * @param {import('./types.js').ColorTheme & { colorSpace?: string }} param0
      */
-    constructor({ colors, mapping }?: {
+    constructor({ colors, mapping, colorSpace }?: {
         colors?: any;
         mapping?: {
             surface: string;
+            ink: string;
             primary: string;
             secondary: string;
+            tertiary: string;
             accent: string;
             success: string;
             warning: string;
@@ -64,31 +69,14 @@ export declare class Theme {
             error: string;
             info: string;
         } | undefined;
+        colorSpace?: string | undefined;
     });
     get colors(): any;
     set colors(colors: any);
-    get mapping(): {
-        surface: string;
-        primary: string;
-        secondary: string;
-        accent: string;
-        success: string;
-        warning: string;
-        danger: string;
-        error: string;
-        info: string;
-    };
-    set mapping(mapping: {
-        surface: string;
-        primary: string;
-        secondary: string;
-        accent: string;
-        success: string;
-        warning: string;
-        danger: string;
-        error: string;
-        info: string;
-    });
+    get mapping(): any;
+    set mapping(mapping: any);
+    get colorSpace(): string;
+    set colorSpace(colorSpace: string);
     mapVariant(color: any, variant: any): {};
     getColorRules(mapping?: null): {};
     getPalette(mapping?: null): {};

package/dist/types.d.ts

@@ -286,6 +286,7 @@ export type ColorMapping = {
      */
     error?: string | undefined;
 };
+export type ColorSpace = "rgb" | "hsl" | "oklch";
 export type ColorTheme = {
     /**
      * - The color mapping.
@@ -297,4 +298,8 @@ export type ColorTheme = {
     colors?: {
         [x: string]: ColorPalette;
     } | undefined;
+    /**
+     * - Color space for CSS variable values ('rgb', 'hsl', or 'oklch').
+     */
+    colorSpace?: ColorSpace | undefined;
 };

package/dist/utils.d.ts

@@ -79,22 +79,33 @@ export function getPathFromKey(key: string): string[];
 export function getSnippet(obj: Object, key: string, defaultSnippet?: null | Function): Function | undefined;
 export function resolveSnippet(snippets: any, proxy: any, fallback?: string): Function | null;
 /**
- * convert hex string to `{r} {g} {b}`
+ * convert hex string to `{r},{g},{b}`
  * @param {string} hex
  * @return {string}
  */
 export function hex2rgb(hex: string): string;
 /**
- * Convert a CSS color value to r,g,b for use in CSS variables.
- * Hex values (#rrggbb) are converted to "r,g,b" for rgba() support.
- * All other CSS color formats (oklch, hsl, named) are returned as-is.
- * Non-string values are returned unchanged.
- * Note: non-hex values will NOT work with UnoCSS opacity utilities like bg-primary/50.
- *
- * @param {unknown} value
- * @returns {unknown}
+ * Convert hex string to OKLCH components: `{L} {C} {H}`
+ * Uses CSS Color Level 4 two-step conversion via XYZ D65 for precision.
+ * @param {string} hex - 6-digit hex color (with or without #)
+ * @returns {string} space-separated OKLCH components for CSS `oklch(L C H / alpha)`
+ */
+export function hex2oklch(hex: string): string;
+/**
+ * Convert OKLCH components back to hex string.
+ * Uses CSS Color Level 4 two-step conversion via XYZ D65 for precision.
+ * @param {number} L - Lightness 0-1
+ * @param {number} C - Chroma >= 0
+ * @param {number} H - Hue 0-360 degrees
+ * @returns {string} hex color string (#rrggbb)
+ */
+export function oklch2hex(L: number, C: number, H: number): string;
+/**
+ * Detects whether an icon value is a CSS class (i-*) or literal text (kanji, emoji, etc.)
+ * @param {string | null | undefined} icon
+ * @returns {boolean} true if icon is a CSS class string
  */
-export function colorToRgb(value: unknown): unknown;
+export function isIconClass(icon: string | null | undefined): boolean;
 /**
  * A utility function that detects if a string is an image URL or image data (base64)
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/core",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Contains core utility functions and classes that can be used in various components.",
   "repository": {
     "type": "git",
@@ -46,6 +46,6 @@
     "ramda": "^0.32.0"
   },
   "devDependencies": {
-    "@rokkit/icons": "1.0.3"
+    "@rokkit/icons": "1.0.5"
   }
 }

package/src/color-space.js

@@ -0,0 +1,308 @@
+/**
+ * ColorSpace adapter strategy pattern.
+ *
+ * Each adapter knows how to convert hex colors to its own representation,
+ * wrap bare channels into a complete CSS color function, and produce
+ * `color-mix()` expressions for theme variables with alpha support.
+ */
+
+// ── Private math helpers (copied from utils.js — not imported) ──────────
+
+/**
+ * Convert sRGB component (0-255) to linear RGB.
+ * @param {number} c - sRGB value 0-255
+ * @returns {number}
+ */
+function srgbToLinear(c) {
+	const s = c / 255
+	return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4)
+}
+
+// Linear sRGB → XYZ D65
+const SRGB_TO_XYZ = [
+	[0.4123907993, 0.3575843394, 0.1804807884],
+	[0.2126390059, 0.7151686788, 0.0721923154],
+	[0.0193308187, 0.1191947798, 0.9505321522]
+]
+// XYZ D65 → LMS
+const XYZ_TO_LMS = [
+	[0.8189330101, 0.3618667424, -0.1288597137],
+	[0.0329845436, 0.9293118715, 0.0361456387],
+	[0.0482003018, 0.2643662691, 0.633851707]
+]
+// LMS^(1/3) → OKLab
+const LMS3_TO_OKLAB = [
+	[0.2104542553, 0.793617785, -0.0040720468],
+	[1.9779984951, -2.428592205, 0.4505937099],
+	[0.0259040371, 0.7827717662, -0.808675766]
+]
+
+/** @param {number[][]} m @param {number[]} v */
+function matMul(m, v) {
+	return m.map((row) => row[0] * v[0] + row[1] * v[1] + row[2] * v[2])
+}
+
+// ── Hex parsing helper ──────────────────────────────────────────────────
+
+/**
+ * Parse a hex string (#rrggbb) into [r, g, b] integers.
+ * @param {string} hex
+ * @returns {number[]}
+ */
+function parseHex(hex) {
+	return hex.match(/\w\w/g).map((x) => parseInt(x, 16))
+}
+
+// ── Hex → HSL conversion ───────────────────────────────────────────────
+
+/**
+ * Convert hex to HSL bare channels: "H S% L%"
+ * @param {string} hex
+ * @returns {string}
+ */
+function hexToHsl(hex) {
+	const [r, g, b] = parseHex(hex)
+	const rn = r / 255
+	const gn = g / 255
+	const bn = b / 255
+	const max = Math.max(rn, gn, bn)
+	const min = Math.min(rn, gn, bn)
+	const l = (max + min) / 2
+
+	if (max === min) return `0 0% ${Math.round(l * 100)}%`
+
+	const d = max - min
+	const s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
+
+	let h = 0
+	if (max === rn) h = ((gn - bn) / d + (gn < bn ? 6 : 0)) / 6
+	else if (max === gn) h = ((bn - rn) / d + 2) / 6
+	else h = ((rn - gn) / d + 4) / 6
+
+	return `${Math.round(h * 360)} ${Math.round(s * 100)}% ${Math.round(l * 100)}%`
+}
+
+// ── Hex → OKLCH conversion ─────────────────────────────────────────────
+
+/**
+ * Convert hex to OKLCH bare channels: "L C H"
+ * @param {string} hex
+ * @returns {string}
+ */
+function hexToOklch(hex) {
+	const [r, g, b] = parseHex(hex)
+	const lin = [srgbToLinear(r), srgbToLinear(g), srgbToLinear(b)]
+
+	const xyz = matMul(SRGB_TO_XYZ, lin)
+	const lms = matMul(XYZ_TO_LMS, xyz)
+	const lms3 = [Math.cbrt(lms[0]), Math.cbrt(lms[1]), Math.cbrt(lms[2])]
+	const [L, a, bk] = matMul(LMS3_TO_OKLAB, lms3)
+
+	const C = Math.sqrt(a * a + bk * bk)
+	let H = (Math.atan2(bk, a) * 180) / Math.PI
+	if (H < 0) H += 360
+
+	const Lr = Math.round(L * 1000000) / 1000000
+	const Cr = Math.round(C * 1000000) / 1000000
+	const Hr = Math.round(H * 10000) / 10000
+
+	return `${Lr} ${Cr} ${Hr}`
+}
+
+// ── Hex regex ───────────────────────────────────────────────────────────
+
+const HEX_RE = /^#[0-9a-fA-F]{6}$/
+
+// ── Base class ──────────────────────────────────────────────────────────
+
+/**
+ * Abstract base class for color space adapters.
+ */
+export class ColorSpace {
+	/** @returns {string} */
+	get name() {
+		throw new Error('Subclass must implement name')
+	}
+
+	/** @returns {string} CSS color-mix interpolation space */
+	get mixSpace() {
+		throw new Error('Subclass must implement mixSpace')
+	}
+
+	/** @returns {string} CSS function name */
+	get fn() {
+		throw new Error('Subclass must implement fn')
+	}
+
+	/**
+	 * Convert a hex color to bare channels in this space.
+	 * @param {string} hex - #rrggbb
+	 * @returns {string}
+	 */
+	fromHex(_hex) {
+		throw new Error('Subclass must implement fromHex')
+	}
+
+	/**
+	 * Wrap any input into a complete CSS color value.
+	 * - hex → convert and wrap
+	 * - bare channels → wrap in fn()
+	 * - already wrapped → pass through
+	 * - non-string / null / undefined → pass through
+	 * - named colors → pass through
+	 * @param {*} value
+	 * @returns {*}
+	 */
+	wrap(_value) {
+		throw new Error('Subclass must implement wrap')
+	}
+
+	/**
+	 * Produce a color-mix expression for theme CSS variables with alpha support.
+	 * @param {string} varName - CSS variable name (e.g. '--color-primary-500')
+	 * @returns {string}
+	 */
+	themeColor(varName) {
+		return `color-mix(in ${this.mixSpace}, var(${varName}) calc(<alpha-value> * 100%), transparent)`
+	}
+
+	/**
+	 * Factory method to create a ColorSpace adapter by name.
+	 * @param {string} space - 'rgb', 'hsl', or 'oklch'
+	 * @returns {ColorSpace}
+	 */
+	static create(space) {
+		switch (space) {
+			case 'rgb':
+				return new RgbColorSpace()
+			case 'hsl':
+				return new HslColorSpace()
+			case 'oklch':
+				return new OklchColorSpace()
+			default:
+				throw new Error(`Unknown color space: ${space}`)
+		}
+	}
+}
+
+// ── RGB adapter ─────────────────────────────────────────────────────────
+
+export class RgbColorSpace extends ColorSpace {
+	get name() {
+		return 'rgb'
+	}
+
+	get mixSpace() {
+		return 'srgb'
+	}
+
+	get fn() {
+		return 'rgb'
+	}
+
+	fromHex(hex) {
+		const [r, g, b] = parseHex(hex)
+		return `${r}, ${g}, ${b}`
+	}
+
+	wrap(value) {
+		if (typeof value !== 'string') return value
+
+		// Already wrapped
+		if (value.startsWith('rgb(') || value.startsWith('rgba(')) return value
+
+		// Hex
+		if (HEX_RE.test(value)) return `rgb(${this.fromHex(value)})`
+
+		// Bare channels: comma-separated or space-separated digits
+		// Comma-separated: "255,0,0" or "255, 0, 0"
+		if (/^\d+\s*,\s*\d+\s*,\s*\d+$/.test(value)) {
+			const parts = value.split(',').map((s) => s.trim())
+			return `rgb(${parts.join(', ')})`
+		}
+		// Space-separated: "255 0 0"
+		if (/^\d+\s+\d+\s+\d+$/.test(value)) {
+			const parts = value.trim().split(/\s+/)
+			return `rgb(${parts.join(', ')})`
+		}
+
+		// Named color or other — pass through
+		return value
+	}
+}
+
+// ── HSL adapter ─────────────────────────────────────────────────────────
+
+export class HslColorSpace extends ColorSpace {
+	get name() {
+		return 'hsl'
+	}
+
+	get mixSpace() {
+		return 'srgb'
+	}
+
+	get fn() {
+		return 'hsl'
+	}
+
+	fromHex(hex) {
+		return hexToHsl(hex)
+	}
+
+	wrap(value) {
+		if (typeof value !== 'string') return value
+
+		// Already wrapped
+		if (value.startsWith('hsl(') || value.startsWith('hsla(')) return value
+
+		// Hex
+		if (HEX_RE.test(value)) return `hsl(${this.fromHex(value)})`
+
+		// Bare channels: "H S% L%" pattern (number, space, number%, space, number%)
+		if (/^\d+\s+\d+%\s+\d+%$/.test(value)) {
+			return `hsl(${value})`
+		}
+
+		// Named color or other — pass through
+		return value
+	}
+}
+
+// ── OKLCH adapter ───────────────────────────────────────────────────────
+
+export class OklchColorSpace extends ColorSpace {
+	get name() {
+		return 'oklch'
+	}
+
+	get mixSpace() {
+		return 'oklch'
+	}
+
+	get fn() {
+		return 'oklch'
+	}
+
+	fromHex(hex) {
+		return hexToOklch(hex)
+	}
+
+	wrap(value) {
+		if (typeof value !== 'string') return value
+
+		// Already wrapped
+		if (value.startsWith('oklch(')) return value
+
+		// Hex
+		if (HEX_RE.test(value)) return `oklch(${this.fromHex(value)})`
+
+		// Bare channels: three space-separated numbers (may contain decimals)
+		if (/^[\d.]+\s+[\d.]+\s+[\d.]+$/.test(value)) {
+			return `oklch(${value})`
+		}
+
+		// Named color or other — pass through
+		return value
+	}
+}

package/src/colors/index.ts

@@ -10,6 +10,7 @@ export const defaultPalette = [
 	'surface',
 	'primary',
 	'secondary',
+	'tertiary',
 	'accent',
 	'success',
 	'warning',

package/src/constants.js

@@ -154,8 +154,10 @@ export const DEFAULT_KEYMAP = {
 
 export const DEFAULT_THEME_MAPPING = {
 	surface: 'slate',
+	ink: 'slate',
 	primary: 'orange',
 	secondary: 'pink',
+	tertiary: 'violet',
 	accent: 'sky',
 	success: 'green',
 	warning: 'yellow',
@@ -177,6 +179,9 @@ export const TONE_MAP = {
 	z9: 900,
 	z10: 950
 }
+
+export const INVERTED_ROLES = new Set(['ink'])
+
 /**
  * Splits an icon name into its group and key components.
  * @param {string} name - The icon name to split.

package/src/index.js

@@ -10,6 +10,7 @@ export * from './nested.js'
 export * from './string.js'
 // skipcq: JS-E1004 - Needed for exposing all functions
 export * from './theme.js'
+export { ColorSpace } from './color-space.js'
 export { FieldMapper } from './field-mapper.js'
 export { getItemAtIndex, getIndexForItem } from './mapped-items.js'
 export { createEmitter } from './events.js'

package/src/theme.ts

@@ -1,32 +1,26 @@
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-nocheck
-import { DEFAULT_THEME_MAPPING, defaultColors, TONE_MAP } from './constants'
+import { DEFAULT_THEME_MAPPING, defaultColors, TONE_MAP, INVERTED_ROLES } from './constants'
 import { shades } from './colors/index'
-import { colorToRgb } from './utils'
-
-const modifiers = {
-	hsl: (value) => `hsl(${value} / <alpha-value>)`,
-	rgb: (value) => `rgb(${value} / <alpha-value>)`,
-	none: (value) => value
-}
+import { ColorSpace } from './color-space'
 
 /**
- * Generate shades for a color using css varuable
+ * Generate shades for a color using css variable and a ColorSpace adapter.
  *
  * @param {string} name
- * @param {string} modifier
- * @returns
+ * @param {string|import('./color-space').ColorSpace} space - color space name or adapter instance
+ * @returns {Record<string|number, string>}
  */
-export function shadesOf(name, modifier = 'none') {
-	const fn = modifier in modifiers ? modifiers[modifier] : modifiers.none
+export function shadesOf(name, space = 'rgb') {
+	const adapter = typeof space === 'string' ? ColorSpace.create(space) : space
 
 	return shades.reduce(
 		(result, shade) => ({
 			...result,
-			[shade]: fn(`var(--color-${name}-${shade})`)
+			[shade]: adapter.themeColor(`--color-${name}-${shade}`)
 		}),
 		{
-			DEFAULT: fn(`var(--color-${name}-500)`)
+			DEFAULT: adapter.themeColor(`--color-${name}-500`)
 		}
 	)
 }
@@ -37,13 +31,14 @@ export function shadesOf(name, modifier = 'none') {
  * @param {string} variant - The name of the variant to generate rules for.
  * @param {Object} colors - The object containing color definitions.
  * @param {Object} mapping - An object that maps variant names to color property names.
+ * @param {import('./color-space').ColorSpace} adapter - ColorSpace adapter instance.
  * @returns {import('./types').ShadeMappings} An array containing the color rules for both light and dark modes.
  */
-function generateColorRules(variant, colors, mapping) {
+function generateColorRules(variant, colors, mapping, adapter) {
 	return ['DEFAULT', ...shades].flatMap((shade) => [
 		{
 			key: shade === 'DEFAULT' ? `--color-${variant}` : `--color-${variant}-${shade}`,
-			value: colorToRgb(colors[mapping[variant]][`${shade}`])
+			value: adapter.wrap(colors[mapping[variant]][`${shade}`])
 		}
 	])
 }
@@ -53,14 +48,16 @@ function generateColorRules(variant, colors, mapping) {
  *
  * @param {Object} [mapping=DEFAULT_THEME_MAPPING] - An object mapping variant names to color property names.
  * @param {Object} [colors=defaultColors]        - The object containing default color definitions.
+ * @param {string} [colorSpace] - Color space name for CSS variable values.
  * @returns {Array<Array>} An array containing two arrays, one for the light theme variant and another for the dark theme.
  */
-export function themeRules(mapping = DEFAULT_THEME_MAPPING, colors = defaultColors) {
+export function themeRules(mapping = DEFAULT_THEME_MAPPING, colors = defaultColors, colorSpace) {
 	mapping = { ...DEFAULT_THEME_MAPPING, ...mapping }
 	colors = { ...defaultColors, ...colors }
+	const adapter = ColorSpace.create(colorSpace || 'rgb')
 	const variants = Object.keys(mapping)
 	const rules = variants
-		.flatMap((variant) => generateColorRules(variant, colors, mapping))
+		.flatMap((variant) => generateColorRules(variant, colors, mapping, adapter))
 		.reduce((acc, { key, value }) => ({ ...acc, [key]: value }), {})
 
 	return rules
@@ -144,20 +141,49 @@ export function contrastShortcuts(name) {
 	]
 }
 
+/**
+ * Fallback chain for nullable color mappings.
+ * If a semantic color is null, it inherits from another semantic color.
+ */
+const COLOR_FALLBACKS = {
+	ink: 'surface',
+	tertiary: 'primary',
+	secondary: 'primary',
+	accent: 'primary',
+	error: 'danger'
+}
+
+/**
+ * Resolves null values in a color mapping by following the fallback chain.
+ * @param {Record<string, string | null>} mapping
+ * @returns {Record<string, string>}
+ */
+function resolveColors(mapping) {
+	const resolved = { ...mapping }
+	for (const [key, fallbackKey] of Object.entries(COLOR_FALLBACKS)) {
+		if (resolved[key] === null || resolved[key] === undefined) {
+			resolved[key] = resolved[fallbackKey] ?? DEFAULT_THEME_MAPPING[fallbackKey]
+		}
+	}
+	return resolved
+}
+
 /**
  * Theme class for managing color palettes, mappings, and semantic shortcuts.
  */
 export class Theme {
 	#colors
 	#mapping
+	#adapter
 
 	/**
 	 *
-	 * @param {import('./types.js').ColorTheme} param0
+	 * @param {import('./types.js').ColorTheme & { colorSpace?: string }} param0
 	 */
-	constructor({ colors = defaultColors, mapping = DEFAULT_THEME_MAPPING } = {}) {
+	constructor({ colors = defaultColors, mapping = DEFAULT_THEME_MAPPING, colorSpace = 'rgb' } = {}) {
 		this.#colors = { ...defaultColors, ...colors }
-		this.#mapping = { ...DEFAULT_THEME_MAPPING, ...mapping }
+		this.#mapping = resolveColors({ ...DEFAULT_THEME_MAPPING, ...mapping })
+		this.#adapter = ColorSpace.create(colorSpace)
 	}
 
 	get colors() {
@@ -171,7 +197,14 @@ export class Theme {
 		return this.#mapping
 	}
 	set mapping(mapping) {
-		this.#mapping = { ...mapping }
+		this.#mapping = resolveColors({ ...mapping })
+	}
+
+	get colorSpace() {
+		return this.#adapter.name
+	}
+	set colorSpace(colorSpace) {
+		this.#adapter = ColorSpace.create(colorSpace)
 	}
 
 	mapVariant(color, variant) {
@@ -180,8 +213,8 @@ export class Theme {
 				...acc,
 				[key]:
 					key === 'DEFAULT'
-						? `rgba(var(--color-${variant}),<alpha-value>)`
-						: `rgba(var(--color-${variant}-${key}),<alpha-value>)`
+						? this.#adapter.themeColor(`--color-${variant}`)
+						: this.#adapter.themeColor(`--color-${variant}-${key}`)
 			}),
 			{}
 		)
@@ -203,7 +236,7 @@ export class Theme {
 		const useColors = { ...defaultColors, ...this.#colors }
 		const variants = Object.keys(useMapping)
 		const rules = variants
-			.flatMap((variant) => generateColorRules(variant, useColors, useMapping))
+			.flatMap((variant) => generateColorRules(variant, useColors, useMapping, this.#adapter))
 			.reduce((acc, { key, value }) => ({ ...acc, [key]: value }), {})
 		return rules
 	}
@@ -226,15 +259,17 @@ export class Theme {
 		const names = Object.keys(this.#mapping)
 
 		const lightLines = names.flatMap((name) =>
-			Object.entries(TONE_MAP).map(
-				([zone, light]) => `  --color-${name}-${zone}: var(--color-${name}-${light});`
-			)
+			Object.entries(TONE_MAP).map(([zone, light]) => {
+				const value = INVERTED_ROLES.has(name) ? 1000 - light : light
+				return `  --color-${name}-${zone}: var(--color-${name}-${value});`
+			})
 		)
 
 		const darkLines = names.flatMap((name) =>
 			Object.entries(TONE_MAP).map(([zone, light]) => {
 				const dark = 1000 - light
-				return `  --color-${name}-${zone}: var(--color-${name}-${dark});`
+				const value = INVERTED_ROLES.has(name) ? light : dark
+				return `  --color-${name}-${zone}: var(--color-${name}-${value});`
 			})
 		)
 

package/src/types.js

@@ -152,9 +152,14 @@
  * @property {string} [error]     - The error color.
  */
 
+/**
+ * @typedef {'rgb' | 'hsl' | 'oklch'} ColorSpace
+ */
+
 /**
  * @typedef {Object} ColorTheme
  * @property {ColorMapping} [mapping] - The color mapping.
  * @property {ColorCollection} [colors] - The color collection.
+ * @property {ColorSpace} [colorSpace] - Color space for CSS variable values ('rgb', 'hsl', or 'oklch').
  */
 export default {}

package/src/utils.js

@@ -195,7 +195,7 @@ export function resolveSnippet(snippets, proxy, fallback = ITEM_SNIPPET) {
 }
 
 /**
- * convert hex string to `{r} {g} {b}`
+ * convert hex string to `{r},{g},{b}`
  * @param {string} hex
  * @return {string}
  */
@@ -205,20 +205,126 @@ export function hex2rgb(hex) {
 }
 
 /**
- * Convert a CSS color value to r,g,b for use in CSS variables.
- * Hex values (#rrggbb) are converted to "r,g,b" for rgba() support.
- * All other CSS color formats (oklch, hsl, named) are returned as-is.
- * Non-string values are returned unchanged.
- * Note: non-hex values will NOT work with UnoCSS opacity utilities like bg-primary/50.
- *
- * @param {unknown} value
- * @returns {unknown}
+ * Convert sRGB component (0-255) to linear RGB.
+ * @param {number} c - sRGB value 0-255
+ * @returns {number}
+ */
+function srgbToLinear(c) {
+	const s = c / 255
+	return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4)
+}
+
+/**
+ * Convert linear RGB to sRGB component (0-255).
+ * @param {number} c - linear value 0-1
+ * @returns {number}
+ */
+function linearToSrgb(c) {
+	const s = c <= 0.0031308 ? c * 12.92 : 1.055 * Math.pow(c, 1 / 2.4) - 0.055
+	return Math.round(Math.max(0, Math.min(255, s * 255)))
+}
+
+// CSS Color Level 4 two-step matrices (via XYZ D65) for round-trip fidelity.
+// Linear sRGB → XYZ D65
+const SRGB_TO_XYZ = [
+	[0.4123907993, 0.3575843394, 0.1804807884],
+	[0.2126390059, 0.7151686788, 0.0721923154],
+	[0.0193308187, 0.1191947798, 0.9505321522]
+]
+// XYZ D65 → LMS
+const XYZ_TO_LMS = [
+	[0.8189330101, 0.3618667424, -0.1288597137],
+	[0.0329845436, 0.9293118715, 0.0361456387],
+	[0.0482003018, 0.2643662691, 0.633851707]
+]
+// LMS^(1/3) → OKLab
+const LMS3_TO_OKLAB = [
+	[0.2104542553, 0.793617785, -0.0040720468],
+	[1.9779984951, -2.428592205, 0.4505937099],
+	[0.0259040371, 0.7827717662, -0.808675766]
+]
+// OKLab → LMS^(1/3)
+const OKLAB_TO_LMS3 = [
+	[1.0, 0.3963377774, 0.2158037573],
+	[1.0, -0.1055613458, -0.0638541728],
+	[1.0, -0.0894841775, -1.291485548]
+]
+// LMS → XYZ D65
+const LMS_TO_XYZ = [
+	[1.2270138511, -0.5577999807, 0.281256149],
+	[-0.0405801784, 1.1122568696, -0.0716766787],
+	[-0.0763812845, -0.4214819784, 1.5861632204]
+]
+// XYZ D65 → linear sRGB
+const XYZ_TO_SRGB = [
+	[3.2409699419, -1.5373831776, -0.4986107603],
+	[-0.9692436363, 1.8759675015, 0.0415550574],
+	[0.0556300797, -0.2039769589, 1.0569715142]
+]
+
+/** @param {number[][]} m @param {number[]} v */
+function matMul(m, v) {
+	return m.map((row) => row[0] * v[0] + row[1] * v[1] + row[2] * v[2])
+}
+
+/**
+ * Convert hex string to OKLCH components: `{L} {C} {H}`
+ * Uses CSS Color Level 4 two-step conversion via XYZ D65 for precision.
+ * @param {string} hex - 6-digit hex color (with or without #)
+ * @returns {string} space-separated OKLCH components for CSS `oklch(L C H / alpha)`
  */
-export function colorToRgb(value) {
-	if (typeof value === 'string' && /^#[0-9a-fA-F]{6}$/.test(value)) {
-		return hex2rgb(value)
+export function hex2oklch(hex) {
+	const [r, g, b] = hex.match(/\w\w/g).map((x) => parseInt(x, 16))
+	const lin = [srgbToLinear(r), srgbToLinear(g), srgbToLinear(b)]
+
+	const xyz = matMul(SRGB_TO_XYZ, lin)
+	const lms = matMul(XYZ_TO_LMS, xyz)
+	const lms3 = [Math.cbrt(lms[0]), Math.cbrt(lms[1]), Math.cbrt(lms[2])]
+	const [L, a, bk] = matMul(LMS3_TO_OKLAB, lms3)
+
+	const C = Math.sqrt(a * a + bk * bk)
+	let H = (Math.atan2(bk, a) * 180) / Math.PI
+	if (H < 0) H += 360
+
+	const Lr = Math.round(L * 1000000) / 1000000
+	const Cr = Math.round(C * 1000000) / 1000000
+	const Hr = Math.round(H * 10000) / 10000
+
+	return `${Lr} ${Cr} ${Hr}`
+}
+
+/**
+ * Convert OKLCH components back to hex string.
+ * Uses CSS Color Level 4 two-step conversion via XYZ D65 for precision.
+ * @param {number} L - Lightness 0-1
+ * @param {number} C - Chroma >= 0
+ * @param {number} H - Hue 0-360 degrees
+ * @returns {string} hex color string (#rrggbb)
+ */
+export function oklch2hex(L, C, H) {
+	const hRad = (H * Math.PI) / 180
+	const lab = [L, C * Math.cos(hRad), C * Math.sin(hRad)]
+
+	const lms3 = matMul(OKLAB_TO_LMS3, lab)
+	const lms = [lms3[0] ** 3, lms3[1] ** 3, lms3[2] ** 3]
+	const xyz = matMul(LMS_TO_XYZ, lms)
+	const lin = matMul(XYZ_TO_SRGB, xyz)
+
+	const toHex = (n) => {
+		const hex = linearToSrgb(n).toString(16)
+		return hex.length === 1 ? `0${hex}` : hex
 	}
-	return value
+	return `#${toHex(lin[0])}${toHex(lin[1])}${toHex(lin[2])}`
+}
+
+/**
+ * Detects whether an icon value is a CSS class (i-*) or literal text (kanji, emoji, etc.)
+ * @param {string | null | undefined} icon
+ * @returns {boolean} true if icon is a CSS class string
+ */
+export function isIconClass(icon) {
+	if (!icon || typeof icon !== 'string') return false
+	return icon.startsWith('i-')
 }
 
 /**