@rokkit/core 1.0.4 → 1.1.0

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,6 +54,7 @@ export namespace DEFAULT_KEYMAP {
 }
 export namespace DEFAULT_THEME_MAPPING {
     let surface: string;
+    let ink: string;
     let primary: string;
     let secondary: string;
     let tertiary: string;
@@ -77,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

@@ -1,9 +1,11 @@
 export * from "./types.js";
 export * from "./constants.js";
+export * from "./named-tokens.ts";
 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/named-tokens.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The 24 canonical named tokens that constitute the "core" emit vocabulary.
+ * Order is significant for tests and for predictable CSS-var output ordering.
+ */
+export declare const NAMED_TOKENS: readonly ["paper", "paper-soft", "paper-mute", "paper-edge", "ink", "ink-mute", "ink-soft", "ink-faint", "primary", "on-primary", "accent", "accent-soft", "success", "success-soft", "warning", "warning-soft", "danger", "danger-soft", "error", "error-soft", "info", "info-soft", "focus-ring", "shadow-tint"];
+export type NamedToken = (typeof NAMED_TOKENS)[number];
+export type SkinRole = 'surface' | 'ink' | 'primary' | 'accent' | 'success' | 'warning' | 'danger' | 'error' | 'info';
+export type ZSlot = 'z0' | 'z1' | 'z2' | 'z3' | 'z4' | 'z5' | 'z6' | 'z7' | 'z8' | 'z9' | 'z10';
+export declare const Z_SLOTS: ZSlot[];
+/**
+ * Maps each named token to the palette shade index that backs it.
+ * 'derived' indicates the token is computed from another palette (e.g., on-primary
+ * picks the paper shade of the surface palette by default for white-on-primary).
+ *
+ *   paper:        50  (lightest surface tone, canvas)
+ *   paper-soft:   100 (card background)
+ *   paper-mute:   200 (subdued panel)
+ *   paper-edge:   400 (hairline border tone)
+ *   ink:          900 (primary text)
+ *   ink-mute:     700 (secondary text)
+ *   ink-soft:     500 (placeholder)
+ *   ink-faint:    300 (disabled)
+ *   primary:      500 (CTA fill)
+ *   on-primary:   derived — surface.50 default (white-on-primary)
+ *   accent / status: 500 (solid)
+ *   *-soft:       100 (tinted-bg companion)
+ *   focus-ring:   500 of accent
+ *   shadow-tint:  900 of ink
+ */
+export declare const NAMED_TOKEN_SHADE_MAP: Record<NamedToken, number | 'derived'>;
+/**
+ * Maps each named token to the skin role whose palette it draws from.
+ */
+export declare const NAMED_TOKEN_ROLE_MAP: Record<NamedToken, SkinRole>;
+/**
+ * Surface z-slot → named slot. Used to emit back-compat aliases like
+ * `--color-surface-z1: var(--paper-soft);` in core mode.
+ *
+ * z2/z3 collapse to paper-mute, z5/z6 to ink-soft, z7/z8 to ink-mute,
+ * z9/z10 to ink. This collapse is the contract: 4 surface tones in core mode.
+ */
+export declare const Z_COLLAPSE_MAP_SURFACE: Record<ZSlot, NamedToken>;
+/**
+ * Ink role uses the inverted z-scale (z0 = darkest = primary text).
+ * In core mode, the same 4+4 named ladder is reused; this table just inverts.
+ */
+export declare const Z_COLLAPSE_MAP_INK: Record<ZSlot, NamedToken>;
+/**
+ * Returns true when the role has a `-soft` companion in the named vocabulary.
+ * Used to decide whether the role's tinted-background slot collapses to
+ * `var(--{role}-soft)` or to `var(--{role})`.
+ */
+export declare function hasSoftCompanion(role: string): boolean;
+export declare function shadeForNamedToken(name: string): number | 'derived' | undefined;
+export declare function roleForNamedToken(name: string): SkinRole | undefined;

package/dist/theme.d.ts

@@ -1,23 +1,24 @@
 /**
- * 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 {import('./utils').ColorSpace} [colorSpace] - Color space for CSS variable values.
+ * @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: {
     surface: string;
+    ink: string;
     primary: string;
     secondary: string;
     tertiary: string;
@@ -51,12 +52,13 @@ export declare class Theme {
     #private;
     /**
      *
-     * @param {import('./types.js').ColorTheme & { colorSpace?: import('./utils').ColorSpace }} param0
+     * @param {import('./types.js').ColorTheme & { colorSpace?: string }} param0
      */
     constructor({ colors, mapping, colorSpace }?: {
         colors?: any;
         mapping?: {
             surface: string;
+            ink: string;
             primary: string;
             secondary: string;
             tertiary: string;
@@ -78,6 +80,60 @@ export declare class Theme {
     mapVariant(color: any, variant: any): {};
     getColorRules(mapping?: null): {};
     getPalette(mapping?: null): {};
+    /**
+     * Returns the named-token layer as a map of `--{name}: <resolved value>` entries.
+     *
+     * Palette values are inlined — there is no `var(--color-{role}-{shade})` indirection.
+     *
+     * `on-primary` is derived: it picks the paper shade (50) of the surface palette so the
+     * default contrast pair is "primary fill + white-ish text." Skins that need a different
+     * pair should override via custom tokens.
+     *
+     * `*-soft` variants resolve to shade 100 of their role's palette.
+     * `shadow-tint` resolves to shade 900 of the ink palette.
+     *
+     * @param {'light' | 'dark'} _mode — accepted for symmetry with future
+     *   dark-aware derivations. Today the Theme is constructed with a mode-resolved
+     *   mapping, so this parameter is informational.
+     * @param perRoleModes — optional map of role → 'core' | 'extended'. When a token's
+     *   role is 'extended', the value is a `var(--color-{role}-{shade})` alias instead
+     *   of the inlined palette value. Defaults to 'core' for all unspecified roles
+     *   (and for the whole map when undefined).
+     */
+    getNamedTokens(_mode?: string, perRoleModes?: Record<string, 'core' | 'extended'>): Record<string, string>;
+    /**
+     * Returns z-alias CSS-var assignments for back-compat in core mode.
+     * `--color-{role}-z{n}` → `var(--{namedSlot})`.
+     *
+     * - surface: uses Z_COLLAPSE_MAP_SURFACE (z2/z3 → paper-mute, z9/z10 → ink, etc.)
+     * - ink: uses Z_COLLAPSE_MAP_INK (inverted scale)
+     * - primary/accent/status: tint-vs-solid 2-state collapse.
+     *   z0–z2 → role-soft (if it exists) else role; z3+ → role.
+     *
+     * This is the back-compat layer: existing `@apply bg-surface-z3` etc. resolves
+     * through these aliases until consumers migrate to the named vocabulary.
+     */
+    /** Accepts SkinRole and any custom skin roles beyond the SkinRole literal union. */
+    getZAliasesForCore(role: string): Record<string, string>;
+    /**
+     * Returns named tokens as CSS-var aliases pointing at the palette layer.
+     * Used in extended mode where the preset emits the full --color-{role}-{shade}
+     * palette; named tokens become thin syntactic aliases over the palette.
+     *
+     * `on-primary` aliases to `var(--color-surface-50)` (derived: paper of surface,
+     * matching the core-mode resolution).
+     */
+    getZAliasesForExtended(): Record<string, string>;
+    /**
+     * Emit the full --color-{role}-{shade} palette CSS vars for a single role.
+     * Mirrors what getPalette does for all roles, but scoped to one.
+     */
+    getPaletteForRole(role: string): Record<string, string>;
+    /**
+     * Emit z-aliases for one role in extended mode — they point at the palette vars,
+     * using TONE_MAP for surface/non-inverted roles and the inverted map for ink.
+     */
+    getZAliasesForRoleExtended(role: string): Record<string, string>;
     getShortcuts(name: any): (string[] | (RegExp | (([, variant, end]: [any, any, any]) => string))[] | (RegExp | (([, end]: [any, any]) => string))[])[];
     /**
      * Generates CSS custom property declarations for the semantic z0–z10 tone scale.

package/dist/utils.d.ts

@@ -101,40 +101,16 @@ export function hex2oklch(hex: string): string;
  */
 export function oklch2hex(L: number, C: number, H: number): string;
 /**
- * Convert hex string to HSL components: `{H} {S}% {L}%`
- * @param {string} hex - 6-digit hex color (with or without #)
- * @returns {string} space-separated HSL components for CSS `hsl(H S% L% / alpha)`
- */
-export function hex2hsl(hex: string): string;
-/** @typedef {'rgb' | 'hsl' | 'oklch'} ColorSpace */
-/**
- * Convert a hex color to the component format for a given color space.
- * - rgb:   "r,g,b"          → for `rgba(var(--x), alpha)`
- * - hsl:   "H S% L%"        → for `hsl(var(--x) / alpha)`
- * - oklch: "L C H"           → for `oklch(var(--x) / alpha)`
+ * Detects whether an icon value is a CSS class or a literal character
+ * (kanji, emoji, single letter, etc.).
  *
- * @param {string} hex - 6-digit hex color (#rrggbb)
- * @param {ColorSpace} space
- * @returns {string}
- */
-export function hexToComponents(hex: string, space: ColorSpace): string;
-/**
- * Convert a CSS color value to components for use in CSS variables.
- *
- * - Hex (#rrggbb): converted to space-appropriate components via hexToComponents.
- * - oklch(...) strings: inner components extracted (e.g. "0.58 0.15 35") so the
- *   value is compatible with the oklch(var(--x) / alpha) wrapper pattern.
- * - All other formats: returned as-is (no opacity-modifier support).
+ * Anything more than one grapheme is treated as a class — including bare
+ * semantic names like `file-svelte` which UnoCSS expands to the configured
+ * icon collection via `iconShortcuts(DEFAULT_ICONS, …)`. Single characters
+ * (kanji, emoji, single letters) render as literal text.
  *
- * @param {unknown} value
- * @param {ColorSpace} [space]
- * @returns {unknown}
- */
-export function colorToRgb(value: unknown, space?: ColorSpace): unknown;
-/**
- * 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
+ * @returns {boolean} true if icon should render as a CSS class
  */
 export function isIconClass(icon: string | null | undefined): boolean;
 /**
@@ -144,4 +120,3 @@ export function isIconClass(icon: string | null | undefined): boolean;
  * @returns {string|null} - Returns the original string if it's an image URL or image data, otherwise null
  */
 export function getImage(str: string): string | null;
-export type ColorSpace = "rgb" | "hsl" | "oklch";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/core",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "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.4"
+    "@rokkit/icons": "1.1.0"
   }
 }

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/constants.js

@@ -79,6 +79,7 @@ export const DEFAULT_ICONS = [
 	'action-close',
 	'action-copy',
 	'action-copysuccess',
+	'action-download',
 	'action-check',
 	'action-pin',
 	'action-save',
@@ -87,6 +88,20 @@ export const DEFAULT_ICONS = [
 	'node-closed',
 	'folder-opened',
 	'folder-closed',
+	'doc-default',
+	'doc-svelte',
+	'doc-js',
+	'doc-ts',
+	'doc-css',
+	'doc-html',
+	'doc-json',
+	'doc-md',
+	'doc-text',
+	'doc-pdf',
+	'doc-archive',
+	'media-image',
+	'media-video',
+	'media-audio',
 	'selector-opened',
 	'selector-closed',
 	'menu-opened',
@@ -133,7 +148,9 @@ export const DEFAULT_ICONS = [
 	'align-vertical-bottom',
 	'align-vertical-middle',
 	'view-code',
-	'view-chart'
+	'view-chart',
+	'view-preview',
+	'view-off'
 ]
 
 export const DEFAULT_OPTIONS = {
@@ -154,6 +171,7 @@ export const DEFAULT_KEYMAP = {
 
 export const DEFAULT_THEME_MAPPING = {
 	surface: 'slate',
+	ink: 'slate',
 	primary: 'orange',
 	secondary: 'pink',
 	tertiary: 'violet',
@@ -178,6 +196,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

@@ -2,6 +2,7 @@
 export * from './types.js'
 // skipcq: JS-E1004 - Needed for exposing all constants
 export * from './constants.js'
+export * from './named-tokens.ts'
 // skipcq: JS-E1004 - Needed for exposing all functions
 export * from './utils.js'
 // skipcq: JS-E1004 - Needed for exposing all functions
@@ -10,6 +11,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/named-tokens.ts

@@ -0,0 +1,161 @@
+/**
+ * The 24 canonical named tokens that constitute the "core" emit vocabulary.
+ * Order is significant for tests and for predictable CSS-var output ordering.
+ */
+export const NAMED_TOKENS = [
+  'paper', 'paper-soft', 'paper-mute', 'paper-edge',
+  'ink', 'ink-mute', 'ink-soft', 'ink-faint',
+  'primary', 'on-primary',
+  'accent', 'accent-soft',
+  'success', 'success-soft',
+  'warning', 'warning-soft',
+  'danger', 'danger-soft',
+  'error', 'error-soft',
+  'info', 'info-soft',
+  'focus-ring', 'shadow-tint'
+] as const
+
+export type NamedToken = (typeof NAMED_TOKENS)[number]
+
+export type SkinRole =
+  | 'surface' | 'ink' | 'primary' | 'accent'
+  | 'success' | 'warning' | 'danger' | 'error' | 'info'
+
+export type ZSlot = 'z0' | 'z1' | 'z2' | 'z3' | 'z4' | 'z5' | 'z6' | 'z7' | 'z8' | 'z9' | 'z10'
+
+export const Z_SLOTS: ZSlot[] = ['z0', 'z1', 'z2', 'z3', 'z4', 'z5', 'z6', 'z7', 'z8', 'z9', 'z10']
+
+/**
+ * Maps each named token to the palette shade index that backs it.
+ * 'derived' indicates the token is computed from another palette (e.g., on-primary
+ * picks the paper shade of the surface palette by default for white-on-primary).
+ *
+ *   paper:        50  (lightest surface tone, canvas)
+ *   paper-soft:   100 (card background)
+ *   paper-mute:   200 (subdued panel)
+ *   paper-edge:   400 (hairline border tone)
+ *   ink:          900 (primary text)
+ *   ink-mute:     700 (secondary text)
+ *   ink-soft:     500 (placeholder)
+ *   ink-faint:    300 (disabled)
+ *   primary:      500 (CTA fill)
+ *   on-primary:   derived — surface.50 default (white-on-primary)
+ *   accent / status: 500 (solid)
+ *   *-soft:       100 (tinted-bg companion)
+ *   focus-ring:   500 of accent
+ *   shadow-tint:  900 of ink
+ */
+export const NAMED_TOKEN_SHADE_MAP: Record<NamedToken, number | 'derived'> = {
+  paper: 50,
+  'paper-soft': 100,
+  'paper-mute': 200,
+  'paper-edge': 400,
+  ink: 900,
+  'ink-mute': 700,
+  'ink-soft': 500,
+  'ink-faint': 300,
+  primary: 500,
+  'on-primary': 'derived',
+  accent: 500,
+  'accent-soft': 100,
+  success: 500,
+  'success-soft': 100,
+  warning: 500,
+  'warning-soft': 100,
+  danger: 500,
+  'danger-soft': 100,
+  error: 500,
+  'error-soft': 100,
+  info: 500,
+  'info-soft': 100,
+  'focus-ring': 500,
+  'shadow-tint': 900
+}
+
+/**
+ * Maps each named token to the skin role whose palette it draws from.
+ */
+export const NAMED_TOKEN_ROLE_MAP: Record<NamedToken, SkinRole> = {
+  paper: 'surface',
+  'paper-soft': 'surface',
+  'paper-mute': 'surface',
+  'paper-edge': 'surface',
+  ink: 'ink',
+  'ink-mute': 'ink',
+  'ink-soft': 'ink',
+  'ink-faint': 'ink',
+  primary: 'primary',
+  'on-primary': 'primary',
+  accent: 'accent',
+  'accent-soft': 'accent',
+  success: 'success',
+  'success-soft': 'success',
+  warning: 'warning',
+  'warning-soft': 'warning',
+  danger: 'danger',
+  'danger-soft': 'danger',
+  error: 'error',
+  'error-soft': 'error',
+  info: 'info',
+  'info-soft': 'info',
+  'focus-ring': 'accent',
+  'shadow-tint': 'ink'
+}
+
+/**
+ * Surface z-slot → named slot. Used to emit back-compat aliases like
+ * `--color-surface-z1: var(--paper-soft);` in core mode.
+ *
+ * z2/z3 collapse to paper-mute, z5/z6 to ink-soft, z7/z8 to ink-mute,
+ * z9/z10 to ink. This collapse is the contract: 4 surface tones in core mode.
+ */
+export const Z_COLLAPSE_MAP_SURFACE: Record<ZSlot, NamedToken> = {
+  z0: 'paper',
+  z1: 'paper-soft',
+  z2: 'paper-mute',
+  z3: 'paper-mute',
+  z4: 'paper-edge',
+  z5: 'ink-soft',
+  z6: 'ink-soft',
+  z7: 'ink-mute',
+  z8: 'ink-mute',
+  z9: 'ink',
+  z10: 'ink'
+}
+
+/**
+ * Ink role uses the inverted z-scale (z0 = darkest = primary text).
+ * In core mode, the same 4+4 named ladder is reused; this table just inverts.
+ */
+export const Z_COLLAPSE_MAP_INK: Record<ZSlot, NamedToken> = {
+  z0: 'ink',
+  z1: 'ink-mute',
+  z2: 'ink-mute',
+  z3: 'ink-soft',
+  z4: 'ink-soft',
+  z5: 'paper-edge',
+  z6: 'paper-edge',
+  z7: 'paper-mute',
+  z8: 'paper-mute',
+  z9: 'paper-soft',
+  z10: 'paper'
+}
+
+const SOFT_TOKENS: Set<string> = new Set(NAMED_TOKENS.filter((t) => t.endsWith('-soft')))
+
+/**
+ * Returns true when the role has a `-soft` companion in the named vocabulary.
+ * Used to decide whether the role's tinted-background slot collapses to
+ * `var(--{role}-soft)` or to `var(--{role})`.
+ */
+export function hasSoftCompanion(role: string): boolean {
+  return SOFT_TOKENS.has(`${role}-soft`)
+}
+
+export function shadeForNamedToken(name: string): number | 'derived' | undefined {
+  return NAMED_TOKEN_SHADE_MAP[name as NamedToken]
+}
+
+export function roleForNamedToken(name: string): SkinRole | undefined {
+  return NAMED_TOKEN_ROLE_MAP[name as NamedToken]
+}

package/src/theme.ts

@@ -1,44 +1,35 @@
 // 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>)`,
-	oklch: (value) => `oklch(${value} / <alpha-value>)`,
-	none: (value) => value
-}
-
-/**
- * CSS function wrappers for each color space, used by mapVariant().
- * rgb uses legacy rgba() comma syntax for broad compatibility.
- * hsl/oklch use modern space-separated syntax with / for alpha.
- */
-const COLOR_SPACE_WRAPPERS = {
-	rgb: (varRef) => `rgba(${varRef},<alpha-value>)`,
-	hsl: (varRef) => `hsl(${varRef} / <alpha-value>)`,
-	oklch: (varRef) => `oklch(${varRef} / <alpha-value>)`
-}
+import { ColorSpace } from './color-space'
+import {
+  NAMED_TOKENS,
+  NAMED_TOKEN_SHADE_MAP,
+  NAMED_TOKEN_ROLE_MAP,
+  Z_COLLAPSE_MAP_SURFACE,
+  Z_COLLAPSE_MAP_INK,
+  Z_SLOTS,
+  hasSoftCompanion
+} from './named-tokens'
 
 /**
- * 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`)
 		}
 	)
 }
@@ -49,14 +40,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('./utils').ColorSpace} [colorSpace] - Color space for component format.
+ * @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, colorSpace) {
+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}`], colorSpace)
+			value: adapter.wrap(colors[mapping[variant]][`${shade}`])
 		}
 	])
 }
@@ -66,15 +57,16 @@ function generateColorRules(variant, colors, mapping, colorSpace) {
  *
  * @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 {import('./utils').ColorSpace} [colorSpace] - Color space for CSS variable values.
+ * @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, 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, colorSpace))
+		.flatMap((variant) => generateColorRules(variant, colors, mapping, adapter))
 		.reduce((acc, { key, value }) => ({ ...acc, [key]: value }), {})
 
 	return rules
@@ -126,9 +118,11 @@ function toneShortcuts({ prefix, name, toneName, lightValue, darkValue }) {
  * @returns {Array} Array of shortcut definitions
  */
 export function semanticShortcuts(name) {
+	const inverted = INVERTED_ROLES.has(name)
 	const shortcuts = []
-	for (const [toneName, lightValue] of Object.entries(TONE_MAP)) {
-		const darkValue = 1000 - lightValue
+	for (const [toneName, toneValue] of Object.entries(TONE_MAP)) {
+		const lightValue = inverted ? 1000 - toneValue : toneValue
+		const darkValue  = inverted ? toneValue : 1000 - toneValue
 		for (const prefix of SEMANTIC_PREFIXES) {
 			shortcuts.push(...toneShortcuts({ prefix, name, toneName, lightValue, darkValue }))
 		}
@@ -163,6 +157,7 @@ export function contrastShortcuts(name) {
  * If a semantic color is null, it inherits from another semantic color.
  */
 const COLOR_FALLBACKS = {
+	ink: 'surface',
 	tertiary: 'primary',
 	secondary: 'primary',
 	accent: 'primary',
@@ -190,16 +185,16 @@ function resolveColors(mapping) {
 export class Theme {
 	#colors
 	#mapping
-	#colorSpace
+	#adapter
 
 	/**
 	 *
-	 * @param {import('./types.js').ColorTheme & { colorSpace?: import('./utils').ColorSpace }} param0
+	 * @param {import('./types.js').ColorTheme & { colorSpace?: string }} param0
 	 */
 	constructor({ colors = defaultColors, mapping = DEFAULT_THEME_MAPPING, colorSpace = 'rgb' } = {}) {
 		this.#colors = { ...defaultColors, ...colors }
 		this.#mapping = resolveColors({ ...DEFAULT_THEME_MAPPING, ...mapping })
-		this.#colorSpace = colorSpace
+		this.#adapter = ColorSpace.create(colorSpace)
 	}
 
 	get colors() {
@@ -217,21 +212,20 @@ export class Theme {
 	}
 
 	get colorSpace() {
-		return this.#colorSpace
+		return this.#adapter.name
 	}
 	set colorSpace(colorSpace) {
-		this.#colorSpace = colorSpace
+		this.#adapter = ColorSpace.create(colorSpace)
 	}
 
 	mapVariant(color, variant) {
-		const wrap = COLOR_SPACE_WRAPPERS[this.#colorSpace] || COLOR_SPACE_WRAPPERS.rgb
 		return Object.keys(color).reduce(
 			(acc, key) => ({
 				...acc,
 				[key]:
 					key === 'DEFAULT'
-						? wrap(`var(--color-${variant})`)
-						: wrap(`var(--color-${variant}-${key})`)
+						? this.#adapter.themeColor(`--color-${variant}`)
+						: this.#adapter.themeColor(`--color-${variant}-${key}`)
 			}),
 			{}
 		)
@@ -253,11 +247,196 @@ export class Theme {
 		const useColors = { ...defaultColors, ...this.#colors }
 		const variants = Object.keys(useMapping)
 		const rules = variants
-			.flatMap((variant) => generateColorRules(variant, useColors, useMapping, this.#colorSpace))
+			.flatMap((variant) => generateColorRules(variant, useColors, useMapping, this.#adapter))
 			.reduce((acc, { key, value }) => ({ ...acc, [key]: value }), {})
 		return rules
 	}
 
+	/**
+	 * Returns the named-token layer as a map of `--{name}: <resolved value>` entries.
+	 *
+	 * Palette values are inlined — there is no `var(--color-{role}-{shade})` indirection.
+	 *
+	 * `on-primary` is derived: it picks the paper shade (50) of the surface palette so the
+	 * default contrast pair is "primary fill + white-ish text." Skins that need a different
+	 * pair should override via custom tokens.
+	 *
+	 * `*-soft` variants resolve to shade 100 of their role's palette.
+	 * `shadow-tint` resolves to shade 900 of the ink palette.
+	 *
+	 * @param {'light' | 'dark'} _mode — accepted for symmetry with future
+	 *   dark-aware derivations. Today the Theme is constructed with a mode-resolved
+	 *   mapping, so this parameter is informational.
+	 * @param perRoleModes — optional map of role → 'core' | 'extended'. When a token's
+	 *   role is 'extended', the value is a `var(--color-{role}-{shade})` alias instead
+	 *   of the inlined palette value. Defaults to 'core' for all unspecified roles
+	 *   (and for the whole map when undefined).
+	 */
+	getNamedTokens(_mode = 'light', perRoleModes?: Record<string, 'core' | 'extended'>) {
+		const colors = { ...defaultColors, ...this.#colors }
+		const result: Record<string, string> = {}
+		for (const name of NAMED_TOKENS) {
+			const value = this.#resolveNamedToken(name, colors, perRoleModes)
+			if (value !== undefined) result[`--${name}`] = value
+		}
+		return result
+	}
+
+	/**
+	 * Resolves a single named token to its CSS value, respecting per-role mode.
+	 * Returns undefined when the role's palette is missing.
+	 */
+	#resolveNamedToken(name: string, colors: Record<string, Record<string, string>>, perRoleModes?: Record<string, 'core' | 'extended'>): string | undefined {
+		const role = NAMED_TOKEN_ROLE_MAP[name]
+		const shadeOrDerived = NAMED_TOKEN_SHADE_MAP[name]
+		const paletteName = this.#mapping[role]
+		if (!paletteName || !colors[paletteName]) return undefined
+		if (shadeOrDerived === 'derived') return this.#resolveDerivedToken(name, colors, perRoleModes)
+		return this.#resolveShadeToken(role, shadeOrDerived as number, colors[paletteName], perRoleModes)
+	}
+
+	/**
+	 * Resolves a shade-based named token value in either core (inline) or extended (alias) mode.
+	 */
+	#resolveShadeToken(role: string, shade: number, palette: Record<string, string>, perRoleModes?: Record<string, 'core' | 'extended'>): string | undefined {
+		const roleMode = perRoleModes?.[role] ?? 'core'
+		if (roleMode === 'extended') return `var(--color-${role}-${shade})`
+		const raw = palette[String(shade)]
+		return raw !== undefined ? this.#adapter.wrap(raw) : undefined
+	}
+
+	/**
+	 * Resolves a 'derived' named token. Today only `on-primary` is derived — it picks
+	 * shade 50 from the surface palette for the default white-on-primary contrast pair.
+	 */
+	#resolveDerivedToken(name: string, colors: Record<string, Record<string, string>>, perRoleModes?: Record<string, 'core' | 'extended'>): string | undefined {
+		if (name === 'on-primary') {
+			const surfacePaletteName = this.#mapping['surface']
+			const surfacePalette = colors[surfacePaletteName]
+			if (!surfacePalette?.['50']) return undefined
+			const surfaceMode = perRoleModes?.['surface'] ?? 'core'
+			if (surfaceMode === 'extended') {
+				return `var(--color-surface-50)`
+			}
+			return this.#adapter.wrap(surfacePalette['50'])
+		}
+		return undefined
+	}
+
+	/**
+	 * Generate z-aliases for surface or ink role using the provided map.
+	 */
+	#getZAliasesFromMap(role: 'surface' | 'ink', map: Record<ZSlot, NamedToken>): Record<string, string> {
+		const result: Record<string, string> = {}
+		// Bare `--color-{role}` alias — points at the role's primary named
+		// slot. Lets preset-wind3 color utilities (bg-surface, from-surface,
+		// to-surface, etc.) resolve in core mode without forcing the full
+		// palette emit. Surface → paper, Ink → ink.
+		result[`--color-${role}`] = role === 'surface' ? 'var(--paper)' : 'var(--ink)'
+		for (const z of Z_SLOTS) {
+			result[`--color-${role}-${z}`] = `var(--${map[z]})`
+		}
+		return result
+	}
+
+	/**
+	 * Generate z-aliases for other roles using tint-vs-solid 2-state collapse.
+	 */
+	#getZAliasesOther(role: string): Record<string, string> {
+		const result: Record<string, string> = {}
+		const hasSoft = hasSoftCompanion(role)
+		const softTarget = hasSoft ? `${role}-soft` : role
+		// Bare `--color-{role}` alias points at the named token so
+		// preset-wind3 color utilities (from-{role}, to-{role}, divide-{role},
+		// etc.) resolve in core mode — they read `--color-{role}` and we'd
+		// otherwise leave it undefined since core mode skips the palette emit.
+		result[`--color-${role}`] = `var(--${role})`
+		for (const z of Z_SLOTS) {
+			const zNum = parseInt(z.slice(1), 10)
+			const target = zNum <= 2 ? softTarget : role
+			result[`--color-${role}-${z}`] = `var(--${target})`
+		}
+		return result
+	}
+
+	/**
+	 * Returns z-alias CSS-var assignments for back-compat in core mode.
+	 * `--color-{role}-z{n}` → `var(--{namedSlot})`.
+	 *
+	 * - surface: uses Z_COLLAPSE_MAP_SURFACE (z2/z3 → paper-mute, z9/z10 → ink, etc.)
+	 * - ink: uses Z_COLLAPSE_MAP_INK (inverted scale)
+	 * - primary/accent/status: tint-vs-solid 2-state collapse.
+	 *   z0–z2 → role-soft (if it exists) else role; z3+ → role.
+	 *
+	 * This is the back-compat layer: existing `@apply bg-surface-z3` etc. resolves
+	 * through these aliases until consumers migrate to the named vocabulary.
+	 */
+	/** Accepts SkinRole and any custom skin roles beyond the SkinRole literal union. */
+	getZAliasesForCore(role: string): Record<string, string> {
+		if (role === 'surface') {
+			return this.#getZAliasesFromMap('surface', Z_COLLAPSE_MAP_SURFACE)
+		}
+		if (role === 'ink') {
+			return this.#getZAliasesFromMap('ink', Z_COLLAPSE_MAP_INK)
+		}
+		return this.#getZAliasesOther(role)
+	}
+
+	/**
+	 * Returns named tokens as CSS-var aliases pointing at the palette layer.
+	 * Used in extended mode where the preset emits the full --color-{role}-{shade}
+	 * palette; named tokens become thin syntactic aliases over the palette.
+	 *
+	 * `on-primary` aliases to `var(--color-surface-50)` (derived: paper of surface,
+	 * matching the core-mode resolution).
+	 */
+	getZAliasesForExtended(): Record<string, string> {
+		const result: Record<string, string> = {}
+		for (const name of NAMED_TOKENS) {
+			const role = NAMED_TOKEN_ROLE_MAP[name]
+			const shadeOrDerived = NAMED_TOKEN_SHADE_MAP[name]
+			if (shadeOrDerived === 'derived') {
+				// on-primary → surface.50
+				result[`--${name}`] = `var(--color-surface-50)`
+				continue
+			}
+			result[`--${name}`] = `var(--color-${role}-${shadeOrDerived})`
+		}
+		return result
+	}
+
+	/**
+	 * Emit the full --color-{role}-{shade} palette CSS vars for a single role.
+	 * Mirrors what getPalette does for all roles, but scoped to one.
+	 */
+	getPaletteForRole(role: string): Record<string, string> {
+		const colors = { ...defaultColors, ...this.#colors }
+		const paletteName = this.#mapping[role]
+		if (!paletteName || !colors[paletteName]) return {}
+		const palette = colors[paletteName]
+		const result: Record<string, string> = {}
+		for (const shade of shades) {
+			if (palette[shade] !== undefined) {
+				result[`--color-${role}-${shade}`] = this.#adapter.wrap(palette[shade])
+			}
+		}
+		return result
+	}
+
+	/**
+	 * Emit z-aliases for one role in extended mode — they point at the palette vars,
+	 * using TONE_MAP for surface/non-inverted roles and the inverted map for ink.
+	 */
+	getZAliasesForRoleExtended(role: string): Record<string, string> {
+		const result: Record<string, string> = {}
+		const isInverted = INVERTED_ROLES.has(role)
+		for (const [zone, light] of Object.entries(TONE_MAP)) {
+			const shade = isInverted ? 1000 - light : light
+			result[`--color-${role}-${zone}`] = `var(--color-${role}-${shade})`
+		}
+		return result
+	}
+
 	getShortcuts(name) {
 		return [...semanticShortcuts(name), ...contrastShortcuts(name)]
 	}
@@ -276,15 +455,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/utils.js

@@ -318,93 +318,22 @@ export function oklch2hex(L, C, H) {
 }
 
 /**
- * Convert hex string to HSL components: `{H} {S}% {L}%`
- * @param {string} hex - 6-digit hex color (with or without #)
- * @returns {string} space-separated HSL components for CSS `hsl(H S% L% / alpha)`
- */
-export function hex2hsl(hex) {
-	const [r, g, b] = hex.match(/\w\w/g).map((x) => parseInt(x, 16))
-
-	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
-
-	const Hr = Math.round(h * 360)
-	const Sr = Math.round(s * 100)
-	const Lr = Math.round(l * 100)
-
-	return `${Hr} ${Sr}% ${Lr}%`
-}
-
-/** @typedef {'rgb' | 'hsl' | 'oklch'} ColorSpace */
-
-/**
- * Convert a hex color to the component format for a given color space.
- * - rgb:   "r,g,b"          → for `rgba(var(--x), alpha)`
- * - hsl:   "H S% L%"        → for `hsl(var(--x) / alpha)`
- * - oklch: "L C H"           → for `oklch(var(--x) / alpha)`
+ * Detects whether an icon value is a CSS class or a literal character
+ * (kanji, emoji, single letter, etc.).
  *
- * @param {string} hex - 6-digit hex color (#rrggbb)
- * @param {ColorSpace} space
- * @returns {string}
- */
-export function hexToComponents(hex, space) {
-	switch (space) {
-		case 'hsl':
-			return hex2hsl(hex)
-		case 'oklch':
-			return hex2oklch(hex)
-		case 'rgb':
-		default:
-			return hex2rgb(hex)
-	}
-}
-
-/**
- * Convert a CSS color value to components for use in CSS variables.
- *
- * - Hex (#rrggbb): converted to space-appropriate components via hexToComponents.
- * - oklch(...) strings: inner components extracted (e.g. "0.58 0.15 35") so the
- *   value is compatible with the oklch(var(--x) / alpha) wrapper pattern.
- * - All other formats: returned as-is (no opacity-modifier support).
+ * Anything more than one grapheme is treated as a class — including bare
+ * semantic names like `file-svelte` which UnoCSS expands to the configured
+ * icon collection via `iconShortcuts(DEFAULT_ICONS, …)`. Single characters
+ * (kanji, emoji, single letters) render as literal text.
  *
- * @param {unknown} value
- * @param {ColorSpace} [space]
- * @returns {unknown}
- */
-export function colorToRgb(value, space) {
-	if (typeof value !== 'string') return value
-	if (/^#[0-9a-fA-F]{6}$/.test(value)) {
-		return space ? hexToComponents(value, space) : hex2rgb(value)
-	}
-	// oklch(...) — extract inner components so the var can be used in oklch(var(--x) / alpha)
-	const oklchMatch = value.match(/^oklch\(\s*([^)]+?)\s*\)$/)
-	if (oklchMatch) return oklchMatch[1]
-	return value
-}
-
-
-/**
- * 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
+ * @returns {boolean} true if icon should render as a CSS class
  */
 export function isIconClass(icon) {
 	if (!icon || typeof icon !== 'string') return false
-	return icon.startsWith('i-')
+	// Spread to count graphemes, not UTF-16 code units, so multi-codepoint
+	// emoji (e.g. 👨‍👩‍👧‍👦) and single CJK characters don't get misread.
+	return [...icon].length > 1
 }
 
 /**