@tenphi/glaze 0.2.0 → 0.4.0

package/README.md

@@ -25,6 +25,7 @@ Glaze generates robust **light**, **dark**, and **high-contrast** color schemes
 - **Light + Dark + High-Contrast** — all schemes from one definition
 - **Per-color hue override** — absolute or relative hue shifts within a theme
 - **Multi-format output** — `okhsl`, `rgb`, `hsl`, `oklch`
+- **CSS custom properties export** — ready-to-use `--var: value;` declarations per scheme
 - **Import/Export** — serialize and restore theme configurations
 - **Create from hex/RGB** — start from an existing brand color
 - **Zero dependencies** — pure math, runs anywhere (Node.js, browser, edge)
@@ -69,7 +70,7 @@ const success = primary.extend({ hue: 157 });
 // Compose into a palette and export
 const palette = glaze.palette({ primary, danger, success });
 const tokens = palette.tokens({ prefix: true });
-// → { '#primary-surface': { '': 'okhsl(...)', '@dark': 'okhsl(...)' }, ... }
+// → { light: { 'primary-surface': 'okhsl(...)', ... }, dark: { 'primary-surface': 'okhsl(...)', ... } }
 ```
 
 ## Core Concepts
@@ -261,7 +262,8 @@ Create a single color token without a full theme:
 const accent = glaze.color({ hue: 280, saturation: 80, lightness: 52, mode: 'fixed' });
 
 accent.resolve();  // → ResolvedColor with light/dark/lightContrast/darkContrast
-accent.token();    // → { '': 'okhsl(...)', '@dark': 'okhsl(...)' }
+accent.token();    // → { '': 'okhsl(...)', '@dark': 'okhsl(...)' }  (tasty format)
+accent.tasty();    // → { '': 'okhsl(...)', '@dark': 'okhsl(...)' }  (same as token)
 accent.json();     // → { light: 'okhsl(...)', dark: 'okhsl(...)' }
 ```
 
@@ -306,7 +308,7 @@ theme.tokens({ format: 'hsl' });       // → 'hsl(270.5, 45.2%, 95.8%)'
 theme.tokens({ format: 'oklch' });     // → 'oklch(96.5% 0.0123 280.0)'
 ```
 
-The `format` option works on all export methods: `theme.tokens()`, `theme.json()`, `palette.tokens()`, `palette.json()`, and standalone `glaze.color().token()` / `.json()`.
+The `format` option works on all export methods: `theme.tokens()`, `theme.tasty()`, `theme.json()`, `theme.css()`, `palette.tokens()`, `palette.tasty()`, `palette.json()`, `palette.css()`, and standalone `glaze.color().token()` / `.tasty()` / `.json()`.
 
 Available formats:
 
@@ -409,18 +411,93 @@ const palette = glaze.palette({ primary, danger, success, warning });
 
 ### Token Export
 
+Tokens are grouped by scheme variant, with plain color names as keys:
+
 ```ts
 const tokens = palette.tokens({ prefix: true });
 // → {
+//   light: { 'primary-surface': 'okhsl(...)', 'danger-surface': 'okhsl(...)' },
+//   dark:  { 'primary-surface': 'okhsl(...)', 'danger-surface': 'okhsl(...)' },
+// }
+```
+
+Custom prefix mapping:
+
+```ts
+palette.tokens({ prefix: { primary: 'brand-', danger: 'error-' } });
+```
+
+### Tasty Export (for [Tasty](https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs) style system)
+
+The `tasty()` method exports tokens in the [Tasty](https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs) style-to-state binding format — `#name` color token keys with state aliases (`''`, `@dark`, etc.):
+
+```ts
+const tastyTokens = palette.tasty({ prefix: true });
+// → {
 //   '#primary-surface': { '': 'okhsl(...)', '@dark': 'okhsl(...)' },
 //   '#danger-surface':  { '': 'okhsl(...)', '@dark': 'okhsl(...)' },
 // }
 ```
 
+Apply as global styles to make color tokens available app-wide:
+
+```ts
+import { useGlobalStyles } from '@cube-dev/ui-kit';
+
+// In your root component
+useGlobalStyles('body', tastyTokens);
+```
+
+For zero-runtime builds, use `tastyStatic` to generate the CSS at build time:
+
+```ts
+import { tastyStatic } from '@cube-dev/ui-kit';
+
+tastyStatic('body', tastyTokens);
+```
+
+Alternatively, register as a recipe via `configure()`:
+
+```ts
+import { configure, tasty } from '@cube-dev/ui-kit';
+
+configure({
+  recipes: {
+    'all-themes': tastyTokens,
+  },
+});
+
+const Page = tasty({
+  styles: {
+    recipe: 'all-themes',
+    fill: '#primary-surface',
+    color: '#primary-text',
+  },
+});
+```
+
+Or spread directly into component styles:
+
+```ts
+const Card = tasty({
+  styles: {
+    ...tastyTokens,
+    fill: '#primary-surface',
+    color: '#primary-text',
+  },
+});
+```
+
 Custom prefix mapping:
 
 ```ts
-palette.tokens({ prefix: { primary: 'brand-', danger: 'error-' } });
+palette.tasty({ prefix: { primary: 'brand-', danger: 'error-' } });
+```
+
+Custom state aliases:
+
+```ts
+palette.tasty({ states: { dark: '@dark', highContrast: '@hc' } });
 ```
 
 ### JSON Export (Framework-Agnostic)
@@ -433,6 +510,53 @@ const data = palette.json({ prefix: true });
 // }
 ```
 
+### CSS Export
+
+Export as CSS custom property declarations, grouped by scheme variant. Each variant is a string of `--name-color: value;` lines that you can wrap in your own selectors and media queries.
+
+```ts
+const css = theme.css();
+// css.light        → "--surface-color: rgb(...);\n--text-color: rgb(...);"
+// css.dark         → "--surface-color: rgb(...);\n--text-color: rgb(...);"
+// css.lightContrast → "--surface-color: rgb(...);\n--text-color: rgb(...);"
+// css.darkContrast  → "--surface-color: rgb(...);\n--text-color: rgb(...);"
+```
+
+Use in a stylesheet:
+
+```ts
+const css = palette.css({ prefix: true });
+
+const stylesheet = `
+:root { ${css.light} }
+@media (prefers-color-scheme: dark) {
+  :root { ${css.dark} }
+}
+`;
+```
+
+Options:
+
+| Option | Default | Description |
+|---|---|---|
+| `format` | `'rgb'` | Color format (`'rgb'`, `'hsl'`, `'okhsl'`, `'oklch'`) |
+| `suffix` | `'-color'` | Suffix appended to each CSS property name |
+| `prefix` | — | (palette only) Same prefix behavior as `tokens()` |
+
+```ts
+// Custom suffix
+theme.css({ suffix: '' });
+// → "--surface: rgb(...);"
+
+// Custom format
+theme.css({ format: 'hsl' });
+// → "--surface-color: hsl(...);"
+
+// Palette with prefix
+palette.css({ prefix: true });
+// → "--primary-surface-color: rgb(...);\n--danger-surface-color: rgb(...);"
+```
+
 ## Output Modes
 
 Control which scheme variants appear in exports:
@@ -440,17 +564,22 @@ Control which scheme variants appear in exports:
 ```ts
 // Light only
 palette.tokens({ modes: { dark: false, highContrast: false } });
+// → { light: { ... } }
 
 // Light + dark (default)
 palette.tokens({ modes: { highContrast: false } });
+// → { light: { ... }, dark: { ... } }
 
 // All four variants
 palette.tokens({ modes: { dark: true, highContrast: true } });
+// → { light: { ... }, dark: { ... }, lightContrast: { ... }, darkContrast: { ... } }
 ```
 
+The `modes` option works the same way on `tokens()`, `tasty()`, `json()`, and `css()`.
+
 Resolution priority (highest first):
 
-1. `tokens({ modes })` / `json({ modes })` — per-call override
+1. `tokens({ modes })` / `tasty({ modes })` / `json({ modes })` / `css({ ... })` — per-call override
 2. `glaze.configure({ modes })` — global config
 3. Built-in default: `{ dark: true, highContrast: false }`
 
@@ -561,12 +690,24 @@ const note    = primary.extend({ hue: 302 });
 
 const palette = glaze.palette({ primary, danger, success, warning, note });
 
-// Export as OKHSL tokens (default)
+// Export as flat token map grouped by variant
 const tokens = palette.tokens({ prefix: true });
+// tokens.light → { 'primary-surface': 'okhsl(...)', 'danger-surface': 'okhsl(...)' }
+// tokens.dark  → { 'primary-surface': 'okhsl(...)', 'danger-surface': 'okhsl(...)' }
+
+// Export as tasty style-to-state bindings (for Tasty style system)
+const tastyTokens = palette.tasty({ prefix: true });
+// tastyTokens['#primary-surface'] → { '': 'okhsl(...)', '@dark': 'okhsl(...)' }
+// Use as a recipe or spread into component styles (see Tasty Export section)
 
 // Export as RGB for broader CSS compatibility
 const rgbTokens = palette.tokens({ prefix: true, format: 'rgb' });
 
+// Export as CSS custom properties (rgb format by default)
+const css = palette.css({ prefix: true });
+// css.light → "--primary-surface-color: rgb(...);\n--danger-surface-color: rgb(...);"
+// css.dark  → "--primary-surface-color: rgb(...);\n--danger-surface-color: rgb(...);"
+
 // Save and restore a theme
 const snapshot = primary.export();
 const restored = glaze.from(snapshot);
@@ -603,8 +744,10 @@ brand.colors({ surface: { lightness: 97 }, text: { base: 'surface', lightness: '
 | `theme.export()` | Export configuration as JSON-safe object |
 | `theme.extend(options)` | Create a child theme |
 | `theme.resolve()` | Resolve all colors |
-| `theme.tokens(options?)` | Export as token map |
+| `theme.tokens(options?)` | Export as flat token map grouped by variant |
+| `theme.tasty(options?)` | Export as [Tasty](https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs) style-to-state bindings |
 | `theme.json(options?)` | Export as plain JSON |
+| `theme.css(options?)` | Export as CSS custom property declarations |
 
 ### Global Configuration
 

package/dist/index.cjs

@@ -998,6 +998,20 @@ function buildTokenMap(resolved, prefix, states, modes, format = "okhsl") {
 	}
 	return tokens;
 }
+function buildFlatTokenMap(resolved, prefix, modes, format = "okhsl") {
+	const result = { light: {} };
+	if (modes.dark) result.dark = {};
+	if (modes.highContrast) result.lightContrast = {};
+	if (modes.dark && modes.highContrast) result.darkContrast = {};
+	for (const [name, color] of resolved) {
+		const key = `${prefix}${name}`;
+		result.light[key] = formatVariant(color.light, format);
+		if (modes.dark) result.dark[key] = formatVariant(color.dark, format);
+		if (modes.highContrast) result.lightContrast[key] = formatVariant(color.lightContrast, format);
+		if (modes.dark && modes.highContrast) result.darkContrast[key] = formatVariant(color.darkContrast, format);
+	}
+	return result;
+}
 function buildJsonMap(resolved, modes, format = "okhsl") {
 	const result = {};
 	for (const [name, color] of resolved) {
@@ -1009,6 +1023,27 @@ function buildJsonMap(resolved, modes, format = "okhsl") {
 	}
 	return result;
 }
+function buildCssMap(resolved, prefix, suffix, format) {
+	const lines = {
+		light: [],
+		dark: [],
+		lightContrast: [],
+		darkContrast: []
+	};
+	for (const [name, color] of resolved) {
+		const prop = `--${prefix}${name}${suffix}`;
+		lines.light.push(`${prop}: ${formatVariant(color.light, format)};`);
+		lines.dark.push(`${prop}: ${formatVariant(color.dark, format)};`);
+		lines.lightContrast.push(`${prop}: ${formatVariant(color.lightContrast, format)};`);
+		lines.darkContrast.push(`${prop}: ${formatVariant(color.darkContrast, format)};`);
+	}
+	return {
+		light: lines.light.join("\n"),
+		dark: lines.dark.join("\n"),
+		lightContrast: lines.lightContrast.join("\n"),
+		darkContrast: lines.darkContrast.join("\n")
+	};
+}
 function createTheme(hue, saturation, initialColors) {
 	let colorDefs = initialColors ? { ...initialColors } : {};
 	return {
@@ -1058,6 +1093,9 @@ function createTheme(hue, saturation, initialColors) {
 			return resolveAllColors(hue, saturation, colorDefs);
 		},
 		tokens(options) {
+			return buildFlatTokenMap(resolveAllColors(hue, saturation, colorDefs), "", resolveModes(options?.modes), options?.format);
+		},
+		tasty(options) {
 			return buildTokenMap(resolveAllColors(hue, saturation, colorDefs), "", {
 				dark: options?.states?.dark ?? globalConfig.states.dark,
 				highContrast: options?.states?.highContrast ?? globalConfig.states.highContrast
@@ -1065,12 +1103,32 @@ function createTheme(hue, saturation, initialColors) {
 		},
 		json(options) {
 			return buildJsonMap(resolveAllColors(hue, saturation, colorDefs), resolveModes(options?.modes), options?.format);
+		},
+		css(options) {
+			return buildCssMap(resolveAllColors(hue, saturation, colorDefs), "", options?.suffix ?? "-color", options?.format ?? "rgb");
 		}
 	};
 }
+function resolvePrefix(options, themeName) {
+	if (options?.prefix === true) return `${themeName}-`;
+	if (typeof options?.prefix === "object" && options.prefix !== null) return options.prefix[themeName] ?? `${themeName}-`;
+	return "";
+}
 function createPalette(themes) {
 	return {
 		tokens(options) {
+			const modes = resolveModes(options?.modes);
+			const allTokens = {};
+			for (const [themeName, theme] of Object.entries(themes)) {
+				const tokens = buildFlatTokenMap(theme.resolve(), resolvePrefix(options, themeName), modes, options?.format);
+				for (const variant of Object.keys(tokens)) {
+					if (!allTokens[variant]) allTokens[variant] = {};
+					Object.assign(allTokens[variant], tokens[variant]);
+				}
+			}
+			return allTokens;
+		},
+		tasty(options) {
 			const states = {
 				dark: options?.states?.dark ?? globalConfig.states.dark,
 				highContrast: options?.states?.highContrast ?? globalConfig.states.highContrast
@@ -1078,11 +1136,7 @@ function createPalette(themes) {
 			const modes = resolveModes(options?.modes);
 			const allTokens = {};
 			for (const [themeName, theme] of Object.entries(themes)) {
-				const resolved = theme.resolve();
-				let prefix = "";
-				if (options?.prefix === true) prefix = `${themeName}-`;
-				else if (typeof options?.prefix === "object" && options.prefix !== null) prefix = options.prefix[themeName] ?? `${themeName}-`;
-				const tokens = buildTokenMap(resolved, prefix, states, modes, options?.format);
+				const tokens = buildTokenMap(theme.resolve(), resolvePrefix(options, themeName), states, modes, options?.format);
 				Object.assign(allTokens, tokens);
 			}
 			return allTokens;
@@ -1092,6 +1146,31 @@ function createPalette(themes) {
 			const result = {};
 			for (const [themeName, theme] of Object.entries(themes)) result[themeName] = buildJsonMap(theme.resolve(), modes, options?.format);
 			return result;
+		},
+		css(options) {
+			const suffix = options?.suffix ?? "-color";
+			const format = options?.format ?? "rgb";
+			const allLines = {
+				light: [],
+				dark: [],
+				lightContrast: [],
+				darkContrast: []
+			};
+			for (const [themeName, theme] of Object.entries(themes)) {
+				const css = buildCssMap(theme.resolve(), resolvePrefix(options, themeName), suffix, format);
+				for (const key of [
+					"light",
+					"dark",
+					"lightContrast",
+					"darkContrast"
+				]) if (css[key]) allLines[key].push(css[key]);
+			}
+			return {
+				light: allLines.light.join("\n"),
+				dark: allLines.dark.join("\n"),
+				lightContrast: allLines.lightContrast.join("\n"),
+				darkContrast: allLines.darkContrast.join("\n")
+			};
 		}
 	};
 }
@@ -1111,6 +1190,12 @@ function createColorToken(input) {
 				highContrast: options?.states?.highContrast ?? globalConfig.states.highContrast
 			}, resolveModes(options?.modes), options?.format)["#__color__"];
 		},
+		tasty(options) {
+			return buildTokenMap(resolveAllColors(input.hue, input.saturation, defs), "", {
+				dark: options?.states?.dark ?? globalConfig.states.dark,
+				highContrast: options?.states?.highContrast ?? globalConfig.states.highContrast
+			}, resolveModes(options?.modes), options?.format)["#__color__"];
+		},
 		json(options) {
 			return buildJsonMap(resolveAllColors(input.hue, input.saturation, defs), resolveModes(options?.modes), options?.format)["__color__"];
 		}