@kbach/react 0.6.35 → 0.6.37

package/dist/{chunk-Y6JF3TZM.mjs → chunk-OUKVG4DI.mjs}

@@ -26,7 +26,7 @@ import {
   transformToWebProps,
   useConditionalGlobalDarkMode,
   useConditionalWidth
-} from "./chunk-O7GFDFVJ.mjs";
+} from "./chunk-ZTDE7V7I.mjs";
 
 // src/jsx-runtime.tsx
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";

package/dist/{chunk-O7GFDFVJ.mjs → chunk-ZTDE7V7I.mjs}

@@ -2203,10 +2203,6 @@ function expandModeAwareColorClasses(classString, colors) {
       out.push(token);
       continue;
     }
-    if (parsed.modifiers.includes("dark") || parsed.modifiers.includes("light")) {
-      out.push(token);
-      continue;
-    }
     const slashIdx = parsed.value.indexOf("/");
     const colorPart = slashIdx > 0 ? parsed.value.slice(0, slashIdx) : parsed.value;
     const opacitySuffix = slashIdx > 0 ? parsed.value.slice(slashIdx) : "";
@@ -2218,6 +2214,12 @@ function expandModeAwareColorClasses(classString, colors) {
     changed = true;
     const bang = parsed.important ? "!" : "";
     const modPrefix = parsed.modifiers.map((m) => `${m}:`).join("");
+    const explicitScheme = parsed.modifiers.map((m) => getModifier(m)?.darkScheme).find((s) => s);
+    if (explicitScheme) {
+      const side = explicitScheme === "dark" ? pair.dark : pair.light;
+      out.push(`${bang}${modPrefix}${parsed.utility}-[${side}]${opacitySuffix}`);
+      continue;
+    }
     out.push(`${bang}${modPrefix}${parsed.utility}-[${pair.light}]${opacitySuffix}`);
     out.push(`${bang}dark:${modPrefix}${parsed.utility}-[${pair.dark}]${opacitySuffix}`);
   }
@@ -2773,6 +2775,48 @@ var defaultTheme = {
   animation: {}
 };
 
+// src/core/generateTypesDts.ts
+var HEADER = `// AUTO-GENERATED by Kbach from your kbach.config.js \u2014 do not edit by hand.
+// Regenerated automatically every time your dev server / Metro picks up a
+// change to that file. Safe (and recommended) to add to .gitignore.
+//
+// Gives useColors()/useSpacing() full autocomplete and typo-catching for your
+// custom colors/spacing keys with zero manual setup \u2014 see KbachCustomColors'
+// doc comment in @kbach/react if you'd rather hand-author this instead.
+import '@kbach/react';
+`;
+var IDENT_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+function propKey(name) {
+  return IDENT_RE.test(name) ? name : JSON.stringify(name);
+}
+function generateKbachTypesDts(theme) {
+  const colorLines = [];
+  for (const [name, value] of Object.entries(theme.colors)) {
+    if (name in defaultColors) continue;
+    const isFlat = typeof value === "string" || isModeAwareColor(value);
+    colorLines.push(`    ${propKey(name)}: ${isFlat ? "string" : "ColorScale"};`);
+  }
+  const spacingLines = [];
+  for (const key of Object.keys(theme.spacing)) {
+    if (key in defaultTheme.spacing) continue;
+    spacingLines.push(`    ${propKey(key)}: true;`);
+  }
+  if (colorLines.length === 0 && spacingLines.length === 0) return "";
+  const body = [
+    colorLines.length > 0 ? `  interface KbachCustomColors {
+${colorLines.join("\n")}
+  }` : null,
+    spacingLines.length > 0 ? `  interface KbachCustomSpacing {
+${spacingLines.join("\n")}
+  }` : null
+  ].filter((s) => s !== null).join("\n\n");
+  return `${HEADER}
+declare module '@kbach/react' {
+${body}
+}
+`;
+}
+
 // src/core/reset.ts
 var RESET_STYLE_ID = "kbach-reset";
 var BASE_RESET = [
@@ -3225,30 +3269,51 @@ function getConfig() {
   configStore.resolved = buildConfig({});
   return configStore.resolved;
 }
-function resolveOneRef(ref, colors) {
-  const lastDash = ref.lastIndexOf("-");
-  if (lastDash <= 0) return null;
-  const name = ref.slice(0, lastDash);
-  const shade = ref.slice(lastDash + 1);
-  if (!/^\d+$/.test(shade)) return null;
-  const entry = colors[name];
-  if (!entry || typeof entry !== "object" || isModeAwareColor(entry)) return null;
-  const target = entry[shade];
-  return typeof target === "string" ? target : null;
-}
 function resolveColorRefs(colors) {
   const MAX_DEPTH = 5;
-  function resolveChain(raw) {
+  function resolveChain(raw, side) {
     let current = raw;
     for (let i = 0; i < MAX_DEPTH; i++) {
-      const next = resolveOneRef(current, colors);
+      const next = resolveOneRef(current, side);
       if (!next || next === current) break;
       current = next;
     }
     return current;
   }
+  function resolveOneRef(ref, side) {
+    const slashIdx = ref.indexOf("/");
+    if (slashIdx > 0) {
+      const baseName = ref.slice(0, slashIdx);
+      const opacity = Number(ref.slice(slashIdx + 1));
+      if (!Number.isFinite(opacity)) return null;
+      let baseRef;
+      const entry2 = colors[baseName];
+      if (typeof entry2 === "string") {
+        baseRef = entry2;
+      } else if (isModeAwareColor(entry2)) {
+        if (!side) return null;
+        baseRef = entry2[side];
+      } else if (entry2 && typeof entry2 === "object" && "6" in entry2) {
+        const v = entry2["6"];
+        baseRef = typeof v === "string" ? v : void 0;
+      }
+      if (baseRef === void 0) return null;
+      const baseHex = resolveChain(baseRef, side);
+      const a = opacity > 1 ? opacity / 100 : opacity;
+      return hexToRgba(baseHex, a);
+    }
+    const lastDash = ref.lastIndexOf("-");
+    if (lastDash <= 0) return null;
+    const name = ref.slice(0, lastDash);
+    const shade = ref.slice(lastDash + 1);
+    if (!/^\d+$/.test(shade)) return null;
+    const entry = colors[name];
+    if (!entry || typeof entry !== "object" || isModeAwareColor(entry)) return null;
+    const target = entry[shade];
+    return typeof target === "string" ? target : null;
+  }
   function resolveValue(val) {
-    return typeof val === "string" ? resolveChain(val) : { light: resolveChain(val.light), dark: resolveChain(val.dark) };
+    return typeof val === "string" ? resolveChain(val, null) : { light: resolveChain(val.light, "light"), dark: resolveChain(val.dark, "dark") };
   }
   const out = {};
   for (const [key, val] of Object.entries(colors)) {
@@ -3941,6 +4006,7 @@ export {
   expandModeAwareColorClasses,
   defaultColors,
   defaultTheme,
+  generateKbachTypesDts,
   RESET_STYLE_ID,
   BASE_RESET,
   syncGlobalWidth,

package/dist/core/index.d.ts

@@ -190,6 +190,20 @@ declare function isModeAwareColor(v: unknown): v is {
  * normal parsing — e.g. `bg-surface` becomes `bg-[#ffffff] dark:bg-[#111827]`.
  * `bg-surface/50` becomes `bg-[#ffffff]/50 dark:bg-[#111827]/50` (the arbitrary-
  * color-plus-opacity composition already resolveColor() already supports).
+ * `hover:bg-surface` becomes `hover:bg-[#ffffff] dark:hover:bg-[#111827]` —
+ * every other modifier already present on the token carries through onto
+ * both halves of the pair unchanged.
+ *
+ * A token that ALREADY carries an explicit dark:/light:/not-dark:/not-light:
+ * modifier (someone writes `dark:hover:bg-primary` on a `primary` that's
+ * already mode-aware, usually out of habit from before it was) isn't split
+ * into a pair — that would be redundant on top of an already-explicit
+ * choice. Instead the matching side is substituted in place and every
+ * modifier, including the dark:/light: itself, is left exactly as written,
+ * so `dark:hover:bg-primary` still only applies in dark mode, using the
+ * dark side (not the resolveColor()-level fallback's light side, which is
+ * only ever reached by a mode-aware pair that skipped this expansion
+ * entirely — not a path normal className resolution takes).
  *
  * Runs once, upfront, purely as a string rewrite — everything downstream
  * (CSS generation, native bucketing/flatten(), the existing dark: reactivity
@@ -200,6 +214,19 @@ declare function isModeAwareColor(v: unknown): v is {
  */
 declare function expandModeAwareColorClasses(classString: string, colors: ThemeColors): string;
 
+/**
+ * Generates the KbachCustomColors/KbachCustomSpacing module-augmentation
+ * source for every color/spacing key `extend.theme` added beyond the built-in
+ * defaults. Called by both the Vite plugin and @kbach/native's Babel plugin —
+ * kept here, shared, so "which colors count as custom" and "flat string vs.
+ * ColorScale" can't drift between the two.
+ *
+ * Returns '' (nothing to write) when the theme adds no custom colors or
+ * spacing keys at all, so callers can skip writing/deleting a file for the
+ * common case of a project still on the stock theme.
+ */
+declare function generateKbachTypesDts(theme: ThemeConfig): string;
+
 declare const defaultColors: {
     transparent: string;
     current: string;
@@ -1308,4 +1335,4 @@ declare function subscribeGlobalWidth(listener: WidthListener): () => void;
  */
 declare function getActiveBreakpoints(width?: number, screens?: Record<string, number>): Set<string>;
 
-export { BASE_RESET, type ColorShades, type ColorValue, type DarkMode, type DefaultColorName, type DefaultSpacingKey, type FrameworkConfig, LRUCache, type ParsedClass, type Platform, type PluginAPI, RESET_STYLE_ID, type ResolvedConfig, type ResolvedStyle, type StyleValue, type ThemeColors, type ThemeConfig, type ThemeMode, type ThemeSpacing, buildConfig, clearCache, clearPluginModifiers, customVariants, defaultColors, defaultTheme, disableRuntimeCSS, escapeCSSSelector, expandModeAwareColorClasses, flatten, generateClassCSS, getActiveBreakpoints, getAllModifierNames, getBuiltinStandaloneNames, getBuiltinUtilityPrefixes, getConfig, getDefaultFontFamily, getEffectiveIsWeb, getGlobalDarkMode, getGlobalScreens, getGlobalWidth, getInteractiveModifiers, getModeModifiers, getModifier, getResponsiveModifiers, initConfig, isKnownModifier, isKnownUtility, isModeAwareColor, isNative, isRuntimeCSSDisabled, isWeb, kbachWarn, matchModifier, normalizeClassString, onConfigChange, parseClass, parseClasses, parseHexRgb, registerModifier, resetConfig, resolve, resolveColor, resolveSizing, resolveSpacing, resolveUtility, setDefaultFontFamily, setGlobalDarkMode, setGlobalWidth, setResolveTarget, splitClassTokens, subscribeGlobalDarkMode, subscribeGlobalWidth, syncGlobalDarkMode, syncGlobalScreens, syncGlobalWidth, toNativeValue, updateConfig };
+export { BASE_RESET, type ColorShades, type ColorValue, type DarkMode, type DefaultColorName, type DefaultSpacingKey, type FrameworkConfig, LRUCache, type ParsedClass, type Platform, type PluginAPI, RESET_STYLE_ID, type ResolvedConfig, type ResolvedStyle, type StyleValue, type ThemeColors, type ThemeConfig, type ThemeMode, type ThemeSpacing, buildConfig, clearCache, clearPluginModifiers, customVariants, defaultColors, defaultTheme, disableRuntimeCSS, escapeCSSSelector, expandModeAwareColorClasses, flatten, generateClassCSS, generateKbachTypesDts, getActiveBreakpoints, getAllModifierNames, getBuiltinStandaloneNames, getBuiltinUtilityPrefixes, getConfig, getDefaultFontFamily, getEffectiveIsWeb, getGlobalDarkMode, getGlobalScreens, getGlobalWidth, getInteractiveModifiers, getModeModifiers, getModifier, getResponsiveModifiers, initConfig, isKnownModifier, isKnownUtility, isModeAwareColor, isNative, isRuntimeCSSDisabled, isWeb, kbachWarn, matchModifier, normalizeClassString, onConfigChange, parseClass, parseClasses, parseHexRgb, registerModifier, resetConfig, resolve, resolveColor, resolveSizing, resolveSpacing, resolveUtility, setDefaultFontFamily, setGlobalDarkMode, setGlobalWidth, setResolveTarget, splitClassTokens, subscribeGlobalDarkMode, subscribeGlobalWidth, syncGlobalDarkMode, syncGlobalScreens, syncGlobalWidth, toNativeValue, updateConfig };

package/dist/core/index.js

@@ -34,6 +34,7 @@ __export(index_exports, {
   expandModeAwareColorClasses: () => expandModeAwareColorClasses,
   flatten: () => flatten,
   generateClassCSS: () => generateClassCSS,
+  generateKbachTypesDts: () => generateKbachTypesDts,
   getActiveBreakpoints: () => getActiveBreakpoints,
   getAllModifierNames: () => getAllModifierNames,
   getBuiltinStandaloneNames: () => getBuiltinStandaloneNames,
@@ -2291,10 +2292,6 @@ function expandModeAwareColorClasses(classString, colors) {
       out.push(token);
       continue;
     }
-    if (parsed.modifiers.includes("dark") || parsed.modifiers.includes("light")) {
-      out.push(token);
-      continue;
-    }
     const slashIdx = parsed.value.indexOf("/");
     const colorPart = slashIdx > 0 ? parsed.value.slice(0, slashIdx) : parsed.value;
     const opacitySuffix = slashIdx > 0 ? parsed.value.slice(slashIdx) : "";
@@ -2306,6 +2303,12 @@ function expandModeAwareColorClasses(classString, colors) {
     changed = true;
     const bang = parsed.important ? "!" : "";
     const modPrefix = parsed.modifiers.map((m) => `${m}:`).join("");
+    const explicitScheme = parsed.modifiers.map((m) => getModifier(m)?.darkScheme).find((s) => s);
+    if (explicitScheme) {
+      const side = explicitScheme === "dark" ? pair.dark : pair.light;
+      out.push(`${bang}${modPrefix}${parsed.utility}-[${side}]${opacitySuffix}`);
+      continue;
+    }
     out.push(`${bang}${modPrefix}${parsed.utility}-[${pair.light}]${opacitySuffix}`);
     out.push(`${bang}dark:${modPrefix}${parsed.utility}-[${pair.dark}]${opacitySuffix}`);
   }
@@ -2861,6 +2864,48 @@ var defaultTheme = {
   animation: {}
 };
 
+// src/core/generateTypesDts.ts
+var HEADER = `// AUTO-GENERATED by Kbach from your kbach.config.js \u2014 do not edit by hand.
+// Regenerated automatically every time your dev server / Metro picks up a
+// change to that file. Safe (and recommended) to add to .gitignore.
+//
+// Gives useColors()/useSpacing() full autocomplete and typo-catching for your
+// custom colors/spacing keys with zero manual setup \u2014 see KbachCustomColors'
+// doc comment in @kbach/react if you'd rather hand-author this instead.
+import '@kbach/react';
+`;
+var IDENT_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+function propKey(name) {
+  return IDENT_RE.test(name) ? name : JSON.stringify(name);
+}
+function generateKbachTypesDts(theme) {
+  const colorLines = [];
+  for (const [name, value] of Object.entries(theme.colors)) {
+    if (name in defaultColors) continue;
+    const isFlat = typeof value === "string" || isModeAwareColor(value);
+    colorLines.push(`    ${propKey(name)}: ${isFlat ? "string" : "ColorScale"};`);
+  }
+  const spacingLines = [];
+  for (const key of Object.keys(theme.spacing)) {
+    if (key in defaultTheme.spacing) continue;
+    spacingLines.push(`    ${propKey(key)}: true;`);
+  }
+  if (colorLines.length === 0 && spacingLines.length === 0) return "";
+  const body = [
+    colorLines.length > 0 ? `  interface KbachCustomColors {
+${colorLines.join("\n")}
+  }` : null,
+    spacingLines.length > 0 ? `  interface KbachCustomSpacing {
+${spacingLines.join("\n")}
+  }` : null
+  ].filter((s) => s !== null).join("\n\n");
+  return `${HEADER}
+declare module '@kbach/react' {
+${body}
+}
+`;
+}
+
 // src/core/reset.ts
 var RESET_STYLE_ID = "kbach-reset";
 var BASE_RESET = [
@@ -3326,30 +3371,51 @@ function getConfig() {
 function resetConfig() {
   configStore.resolved = null;
 }
-function resolveOneRef(ref, colors) {
-  const lastDash = ref.lastIndexOf("-");
-  if (lastDash <= 0) return null;
-  const name = ref.slice(0, lastDash);
-  const shade = ref.slice(lastDash + 1);
-  if (!/^\d+$/.test(shade)) return null;
-  const entry = colors[name];
-  if (!entry || typeof entry !== "object" || isModeAwareColor(entry)) return null;
-  const target = entry[shade];
-  return typeof target === "string" ? target : null;
-}
 function resolveColorRefs(colors) {
   const MAX_DEPTH = 5;
-  function resolveChain(raw) {
+  function resolveChain(raw, side) {
     let current = raw;
     for (let i = 0; i < MAX_DEPTH; i++) {
-      const next = resolveOneRef(current, colors);
+      const next = resolveOneRef(current, side);
       if (!next || next === current) break;
       current = next;
     }
     return current;
   }
+  function resolveOneRef(ref, side) {
+    const slashIdx = ref.indexOf("/");
+    if (slashIdx > 0) {
+      const baseName = ref.slice(0, slashIdx);
+      const opacity = Number(ref.slice(slashIdx + 1));
+      if (!Number.isFinite(opacity)) return null;
+      let baseRef;
+      const entry2 = colors[baseName];
+      if (typeof entry2 === "string") {
+        baseRef = entry2;
+      } else if (isModeAwareColor(entry2)) {
+        if (!side) return null;
+        baseRef = entry2[side];
+      } else if (entry2 && typeof entry2 === "object" && "6" in entry2) {
+        const v = entry2["6"];
+        baseRef = typeof v === "string" ? v : void 0;
+      }
+      if (baseRef === void 0) return null;
+      const baseHex = resolveChain(baseRef, side);
+      const a = opacity > 1 ? opacity / 100 : opacity;
+      return hexToRgba(baseHex, a);
+    }
+    const lastDash = ref.lastIndexOf("-");
+    if (lastDash <= 0) return null;
+    const name = ref.slice(0, lastDash);
+    const shade = ref.slice(lastDash + 1);
+    if (!/^\d+$/.test(shade)) return null;
+    const entry = colors[name];
+    if (!entry || typeof entry !== "object" || isModeAwareColor(entry)) return null;
+    const target = entry[shade];
+    return typeof target === "string" ? target : null;
+  }
   function resolveValue(val) {
-    return typeof val === "string" ? resolveChain(val) : { light: resolveChain(val.light), dark: resolveChain(val.dark) };
+    return typeof val === "string" ? resolveChain(val, null) : { light: resolveChain(val.light, "light"), dark: resolveChain(val.dark, "dark") };
   }
   const out = {};
   for (const [key, val] of Object.entries(colors)) {
@@ -3502,6 +3568,7 @@ function subscribeGlobalDarkMode(callback) {
   expandModeAwareColorClasses,
   flatten,
   generateClassCSS,
+  generateKbachTypesDts,
   getActiveBreakpoints,
   getAllModifierNames,
   getBuiltinStandaloneNames,

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import * as React from 'react';
 import React__default, { ReactNode, ComponentType, ForwardRefExoticComponent } from 'react';
 import * as __core from './core';
 import { ThemeMode, ResolvedConfig, DefaultColorName, defaultColors, ThemeColors, DefaultSpacingKey, ThemeSpacing, FrameworkConfig, StyleValue, ResolvedStyle } from './core';
-export { DefaultColorName, DefaultSpacingKey, FrameworkConfig, ParsedClass, PluginAPI, ResolvedConfig, ResolvedStyle, StyleValue, ThemeConfig, ThemeMode, buildConfig, clearCache, defaultColors, defaultTheme, disableRuntimeCSS, flatten, getConfig, initConfig, normalizeClassString, parseClass, parseClasses, resolve, setResolveTarget, splitClassTokens, updateConfig } from './core';
+export { DefaultColorName, DefaultSpacingKey, FrameworkConfig, ParsedClass, PluginAPI, ResolvedConfig, ResolvedStyle, StyleValue, ThemeConfig, ThemeMode, buildConfig, clearCache, defaultColors, defaultTheme, disableRuntimeCSS, flatten, generateKbachTypesDts, getConfig, initConfig, normalizeClassString, parseClass, parseClasses, resolve, setResolveTarget, splitClassTokens, updateConfig } from './core';
 export { r as registerWebElement } from './web-substitute-CfpYFnE7.js';
 
 interface ThemeContextValue {

package/dist/index.js

@@ -42,6 +42,7 @@ __export(index_exports, {
   defaultTheme: () => import_core12.defaultTheme,
   disableRuntimeCSS: () => import_core12.disableRuntimeCSS,
   flatten: () => import_core12.flatten,
+  generateKbachTypesDts: () => import_core12.generateKbachTypesDts,
   getConfig: () => import_core12.getConfig,
   initConfig: () => import_core12.initConfig,
   kb: () => kb,
@@ -1113,6 +1114,7 @@ var import_core12 = require("./core");
   defaultTheme,
   disableRuntimeCSS,
   flatten,
+  generateKbachTypesDts,
   getConfig,
   initConfig,
   kb,

package/dist/index.mjs

@@ -11,6 +11,7 @@ import {
   defaultTheme,
   disableRuntimeCSS,
   flatten,
+  generateKbachTypesDts,
   getActiveBreakpoints,
   getConfig,
   getEffectiveIsWeb,
@@ -44,7 +45,7 @@ import {
   useGlobalDarkMode,
   useGlobalWidth,
   useSyncExternalStore
-} from "./chunk-O7GFDFVJ.mjs";
+} from "./chunk-ZTDE7V7I.mjs";
 
 // src/context.tsx
 import { createContext, useContext } from "react";
@@ -549,6 +550,7 @@ export {
   defaultTheme,
   disableRuntimeCSS,
   flatten,
+  generateKbachTypesDts,
   getConfig,
   initConfig,
   kb,

package/dist/jsx-dev-runtime.mjs

@@ -3,8 +3,8 @@ import {
   Fragment,
   jsx,
   jsxs
-} from "./chunk-Y6JF3TZM.mjs";
-import "./chunk-O7GFDFVJ.mjs";
+} from "./chunk-OUKVG4DI.mjs";
+import "./chunk-ZTDE7V7I.mjs";
 
 // src/jsx-dev-runtime.tsx
 function jsxDEV(type, props, key, isStaticChildren, source, self) {

package/dist/jsx-runtime.mjs

@@ -4,10 +4,10 @@ import {
   _invalidateDefaultFontCache,
   jsx,
   jsxs
-} from "./chunk-Y6JF3TZM.mjs";
+} from "./chunk-OUKVG4DI.mjs";
 import {
   registerWebElement
-} from "./chunk-O7GFDFVJ.mjs";
+} from "./chunk-ZTDE7V7I.mjs";
 export {
   Fragment,
   _invalidateDefaultFontCache,

package/dist/vite-plugin.js

@@ -2800,10 +2800,6 @@ function expandModeAwareColorClasses(classString, colors) {
       out.push(token);
       continue;
     }
-    if (parsed.modifiers.includes("dark") || parsed.modifiers.includes("light")) {
-      out.push(token);
-      continue;
-    }
     const slashIdx = parsed.value.indexOf("/");
     const colorPart = slashIdx > 0 ? parsed.value.slice(0, slashIdx) : parsed.value;
     const opacitySuffix = slashIdx > 0 ? parsed.value.slice(slashIdx) : "";
@@ -2815,6 +2811,12 @@ function expandModeAwareColorClasses(classString, colors) {
     changed = true;
     const bang = parsed.important ? "!" : "";
     const modPrefix = parsed.modifiers.map((m) => `${m}:`).join("");
+    const explicitScheme = parsed.modifiers.map((m) => getModifier(m)?.darkScheme).find((s) => s);
+    if (explicitScheme) {
+      const side = explicitScheme === "dark" ? pair.dark : pair.light;
+      out.push(`${bang}${modPrefix}${parsed.utility}-[${side}]${opacitySuffix}`);
+      continue;
+    }
     out.push(`${bang}${modPrefix}${parsed.utility}-[${pair.light}]${opacitySuffix}`);
     out.push(`${bang}dark:${modPrefix}${parsed.utility}-[${pair.dark}]${opacitySuffix}`);
   }
@@ -3070,30 +3072,51 @@ function deepMerge(base, override) {
   return result;
 }
 var configStore = { resolved: null, listeners: /* @__PURE__ */ new Set(), customVariants: {} };
-function resolveOneRef(ref, colors) {
-  const lastDash = ref.lastIndexOf("-");
-  if (lastDash <= 0) return null;
-  const name = ref.slice(0, lastDash);
-  const shade = ref.slice(lastDash + 1);
-  if (!/^\d+$/.test(shade)) return null;
-  const entry = colors[name];
-  if (!entry || typeof entry !== "object" || isModeAwareColor(entry)) return null;
-  const target = entry[shade];
-  return typeof target === "string" ? target : null;
-}
 function resolveColorRefs(colors) {
   const MAX_DEPTH = 5;
-  function resolveChain(raw) {
+  function resolveChain(raw, side) {
     let current = raw;
     for (let i = 0; i < MAX_DEPTH; i++) {
-      const next = resolveOneRef(current, colors);
+      const next = resolveOneRef(current, side);
       if (!next || next === current) break;
       current = next;
     }
     return current;
   }
+  function resolveOneRef(ref, side) {
+    const slashIdx = ref.indexOf("/");
+    if (slashIdx > 0) {
+      const baseName = ref.slice(0, slashIdx);
+      const opacity = Number(ref.slice(slashIdx + 1));
+      if (!Number.isFinite(opacity)) return null;
+      let baseRef;
+      const entry2 = colors[baseName];
+      if (typeof entry2 === "string") {
+        baseRef = entry2;
+      } else if (isModeAwareColor(entry2)) {
+        if (!side) return null;
+        baseRef = entry2[side];
+      } else if (entry2 && typeof entry2 === "object" && "6" in entry2) {
+        const v = entry2["6"];
+        baseRef = typeof v === "string" ? v : void 0;
+      }
+      if (baseRef === void 0) return null;
+      const baseHex = resolveChain(baseRef, side);
+      const a = opacity > 1 ? opacity / 100 : opacity;
+      return hexToRgba(baseHex, a);
+    }
+    const lastDash = ref.lastIndexOf("-");
+    if (lastDash <= 0) return null;
+    const name = ref.slice(0, lastDash);
+    const shade = ref.slice(lastDash + 1);
+    if (!/^\d+$/.test(shade)) return null;
+    const entry = colors[name];
+    if (!entry || typeof entry !== "object" || isModeAwareColor(entry)) return null;
+    const target = entry[shade];
+    return typeof target === "string" ? target : null;
+  }
   function resolveValue(val) {
-    return typeof val === "string" ? resolveChain(val) : { light: resolveChain(val.light), dark: resolveChain(val.dark) };
+    return typeof val === "string" ? resolveChain(val, null) : { light: resolveChain(val.light, "light"), dark: resolveChain(val.dark, "dark") };
   }
   const out = {};
   for (const [key, val] of Object.entries(colors)) {
@@ -3196,6 +3219,48 @@ function makePluginAPI(theme) {
 }
 var customVariants = configStore.customVariants;
 
+// src/core/generateTypesDts.ts
+var HEADER = `// AUTO-GENERATED by Kbach from your kbach.config.js \u2014 do not edit by hand.
+// Regenerated automatically every time your dev server / Metro picks up a
+// change to that file. Safe (and recommended) to add to .gitignore.
+//
+// Gives useColors()/useSpacing() full autocomplete and typo-catching for your
+// custom colors/spacing keys with zero manual setup \u2014 see KbachCustomColors'
+// doc comment in @kbach/react if you'd rather hand-author this instead.
+import '@kbach/react';
+`;
+var IDENT_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+function propKey(name) {
+  return IDENT_RE.test(name) ? name : JSON.stringify(name);
+}
+function generateKbachTypesDts(theme) {
+  const colorLines = [];
+  for (const [name, value] of Object.entries(theme.colors)) {
+    if (name in defaultColors) continue;
+    const isFlat = typeof value === "string" || isModeAwareColor(value);
+    colorLines.push(`    ${propKey(name)}: ${isFlat ? "string" : "ColorScale"};`);
+  }
+  const spacingLines = [];
+  for (const key of Object.keys(theme.spacing)) {
+    if (key in defaultTheme.spacing) continue;
+    spacingLines.push(`    ${propKey(key)}: true;`);
+  }
+  if (colorLines.length === 0 && spacingLines.length === 0) return "";
+  const body = [
+    colorLines.length > 0 ? `  interface KbachCustomColors {
+${colorLines.join("\n")}
+  }` : null,
+    spacingLines.length > 0 ? `  interface KbachCustomSpacing {
+${spacingLines.join("\n")}
+  }` : null
+  ].filter((s) => s !== null).join("\n\n");
+  return `${HEADER}
+declare module '@kbach/react' {
+${body}
+}
+`;
+}
+
 // src/vite-plugin.ts
 var process2 = import_node_process.default;
 function normPath(p) {
@@ -3216,6 +3281,9 @@ function warn(message) {
 function warnBlock(header, ...lines) {
   console.warn([`${TAG()} ${yellow(header)}`, ...lines].join("\n"));
 }
+function log(message) {
+  console.log(`${TAG()} ${message}`);
+}
 function findLineCol(code, needle) {
   const index = code.indexOf(needle);
   if (index === -1) return null;
@@ -3481,6 +3549,28 @@ ${block}` : block;
   (0, import_fs.writeFileSync)(filePath, next, "utf-8");
   return true;
 }
+function writeKbachTypesDts(root, theme) {
+  const filePath = (0, import_path.join)(root, "kbach-types.d.ts");
+  const content = generateKbachTypesDts(theme);
+  let existing = null;
+  try {
+    existing = (0, import_fs.readFileSync)(filePath, "utf-8");
+  } catch {
+  }
+  if (content === (existing ?? "")) return;
+  try {
+    if (content === "") {
+      (0, import_fs.unlinkSync)(filePath);
+    } else {
+      const isNew = existing === null;
+      (0, import_fs.writeFileSync)(filePath, content, "utf-8");
+      if (isNew) {
+        log(`Generated kbach-types.d.ts \u2014 gives useColors()/useSpacing() autocomplete for your custom colors/spacing keys. Safe to add to .gitignore.`);
+      }
+    }
+  } catch {
+  }
+}
 function toNumericScreens(screens) {
   const out = {};
   for (const [k, v] of Object.entries(screens)) {
@@ -3700,6 +3790,7 @@ function kbach(userConfigOrOptions) {
     },
     configResolved(resolved) {
       root = resolved.root;
+      writeKbachTypesDts(root, cfg.theme);
       const names = new Set(resolved.plugins.map((p) => p.name));
       if (names.has("react-router") && names.has("vite:react-refresh")) {
         warnBlock(

package/dist/vite-plugin.mjs

@@ -1,5 +1,5 @@
 // src/vite-plugin.ts
-import { readFileSync, writeFileSync, readdirSync, statSync } from "fs";
+import { readFileSync, writeFileSync, unlinkSync, readdirSync, statSync } from "fs";
 import { join, relative } from "path";
 import processImport from "process";
 
@@ -2766,10 +2766,6 @@ function expandModeAwareColorClasses(classString, colors) {
       out.push(token);
       continue;
     }
-    if (parsed.modifiers.includes("dark") || parsed.modifiers.includes("light")) {
-      out.push(token);
-      continue;
-    }
     const slashIdx = parsed.value.indexOf("/");
     const colorPart = slashIdx > 0 ? parsed.value.slice(0, slashIdx) : parsed.value;
     const opacitySuffix = slashIdx > 0 ? parsed.value.slice(slashIdx) : "";
@@ -2781,6 +2777,12 @@ function expandModeAwareColorClasses(classString, colors) {
     changed = true;
     const bang = parsed.important ? "!" : "";
     const modPrefix = parsed.modifiers.map((m) => `${m}:`).join("");
+    const explicitScheme = parsed.modifiers.map((m) => getModifier(m)?.darkScheme).find((s) => s);
+    if (explicitScheme) {
+      const side = explicitScheme === "dark" ? pair.dark : pair.light;
+      out.push(`${bang}${modPrefix}${parsed.utility}-[${side}]${opacitySuffix}`);
+      continue;
+    }
     out.push(`${bang}${modPrefix}${parsed.utility}-[${pair.light}]${opacitySuffix}`);
     out.push(`${bang}dark:${modPrefix}${parsed.utility}-[${pair.dark}]${opacitySuffix}`);
   }
@@ -3036,30 +3038,51 @@ function deepMerge(base, override) {
   return result;
 }
 var configStore = { resolved: null, listeners: /* @__PURE__ */ new Set(), customVariants: {} };
-function resolveOneRef(ref, colors) {
-  const lastDash = ref.lastIndexOf("-");
-  if (lastDash <= 0) return null;
-  const name = ref.slice(0, lastDash);
-  const shade = ref.slice(lastDash + 1);
-  if (!/^\d+$/.test(shade)) return null;
-  const entry = colors[name];
-  if (!entry || typeof entry !== "object" || isModeAwareColor(entry)) return null;
-  const target = entry[shade];
-  return typeof target === "string" ? target : null;
-}
 function resolveColorRefs(colors) {
   const MAX_DEPTH = 5;
-  function resolveChain(raw) {
+  function resolveChain(raw, side) {
     let current = raw;
     for (let i = 0; i < MAX_DEPTH; i++) {
-      const next = resolveOneRef(current, colors);
+      const next = resolveOneRef(current, side);
       if (!next || next === current) break;
       current = next;
     }
     return current;
   }
+  function resolveOneRef(ref, side) {
+    const slashIdx = ref.indexOf("/");
+    if (slashIdx > 0) {
+      const baseName = ref.slice(0, slashIdx);
+      const opacity = Number(ref.slice(slashIdx + 1));
+      if (!Number.isFinite(opacity)) return null;
+      let baseRef;
+      const entry2 = colors[baseName];
+      if (typeof entry2 === "string") {
+        baseRef = entry2;
+      } else if (isModeAwareColor(entry2)) {
+        if (!side) return null;
+        baseRef = entry2[side];
+      } else if (entry2 && typeof entry2 === "object" && "6" in entry2) {
+        const v = entry2["6"];
+        baseRef = typeof v === "string" ? v : void 0;
+      }
+      if (baseRef === void 0) return null;
+      const baseHex = resolveChain(baseRef, side);
+      const a = opacity > 1 ? opacity / 100 : opacity;
+      return hexToRgba(baseHex, a);
+    }
+    const lastDash = ref.lastIndexOf("-");
+    if (lastDash <= 0) return null;
+    const name = ref.slice(0, lastDash);
+    const shade = ref.slice(lastDash + 1);
+    if (!/^\d+$/.test(shade)) return null;
+    const entry = colors[name];
+    if (!entry || typeof entry !== "object" || isModeAwareColor(entry)) return null;
+    const target = entry[shade];
+    return typeof target === "string" ? target : null;
+  }
   function resolveValue(val) {
-    return typeof val === "string" ? resolveChain(val) : { light: resolveChain(val.light), dark: resolveChain(val.dark) };
+    return typeof val === "string" ? resolveChain(val, null) : { light: resolveChain(val.light, "light"), dark: resolveChain(val.dark, "dark") };
   }
   const out = {};
   for (const [key, val] of Object.entries(colors)) {
@@ -3162,6 +3185,48 @@ function makePluginAPI(theme) {
 }
 var customVariants = configStore.customVariants;
 
+// src/core/generateTypesDts.ts
+var HEADER = `// AUTO-GENERATED by Kbach from your kbach.config.js \u2014 do not edit by hand.
+// Regenerated automatically every time your dev server / Metro picks up a
+// change to that file. Safe (and recommended) to add to .gitignore.
+//
+// Gives useColors()/useSpacing() full autocomplete and typo-catching for your
+// custom colors/spacing keys with zero manual setup \u2014 see KbachCustomColors'
+// doc comment in @kbach/react if you'd rather hand-author this instead.
+import '@kbach/react';
+`;
+var IDENT_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+function propKey(name) {
+  return IDENT_RE.test(name) ? name : JSON.stringify(name);
+}
+function generateKbachTypesDts(theme) {
+  const colorLines = [];
+  for (const [name, value] of Object.entries(theme.colors)) {
+    if (name in defaultColors) continue;
+    const isFlat = typeof value === "string" || isModeAwareColor(value);
+    colorLines.push(`    ${propKey(name)}: ${isFlat ? "string" : "ColorScale"};`);
+  }
+  const spacingLines = [];
+  for (const key of Object.keys(theme.spacing)) {
+    if (key in defaultTheme.spacing) continue;
+    spacingLines.push(`    ${propKey(key)}: true;`);
+  }
+  if (colorLines.length === 0 && spacingLines.length === 0) return "";
+  const body = [
+    colorLines.length > 0 ? `  interface KbachCustomColors {
+${colorLines.join("\n")}
+  }` : null,
+    spacingLines.length > 0 ? `  interface KbachCustomSpacing {
+${spacingLines.join("\n")}
+  }` : null
+  ].filter((s) => s !== null).join("\n\n");
+  return `${HEADER}
+declare module '@kbach/react' {
+${body}
+}
+`;
+}
+
 // src/vite-plugin.ts
 var process2 = processImport;
 function normPath(p) {
@@ -3182,6 +3247,9 @@ function warn(message) {
 function warnBlock(header, ...lines) {
   console.warn([`${TAG()} ${yellow(header)}`, ...lines].join("\n"));
 }
+function log(message) {
+  console.log(`${TAG()} ${message}`);
+}
 function findLineCol(code, needle) {
   const index = code.indexOf(needle);
   if (index === -1) return null;
@@ -3447,6 +3515,28 @@ ${block}` : block;
   writeFileSync(filePath, next, "utf-8");
   return true;
 }
+function writeKbachTypesDts(root, theme) {
+  const filePath = join(root, "kbach-types.d.ts");
+  const content = generateKbachTypesDts(theme);
+  let existing = null;
+  try {
+    existing = readFileSync(filePath, "utf-8");
+  } catch {
+  }
+  if (content === (existing ?? "")) return;
+  try {
+    if (content === "") {
+      unlinkSync(filePath);
+    } else {
+      const isNew = existing === null;
+      writeFileSync(filePath, content, "utf-8");
+      if (isNew) {
+        log(`Generated kbach-types.d.ts \u2014 gives useColors()/useSpacing() autocomplete for your custom colors/spacing keys. Safe to add to .gitignore.`);
+      }
+    }
+  } catch {
+  }
+}
 function toNumericScreens(screens) {
   const out = {};
   for (const [k, v] of Object.entries(screens)) {
@@ -3666,6 +3756,7 @@ function kbach(userConfigOrOptions) {
     },
     configResolved(resolved) {
       root = resolved.root;
+      writeKbachTypesDts(root, cfg.theme);
       const names = new Set(resolved.plugins.map((p) => p.name));
       if (names.has("react-router") && names.has("vite:react-refresh")) {
         warnBlock(

package/kbach-react.md

@@ -189,7 +189,9 @@ colors.white              // '#ffffff'
 colors['white/20']        // 'rgba(255,255,255,0.2)'
 colors.alpha('#ff6b35', 60) // 'rgba(255,107,53,0.6)'
 ```
-Typed against the built-in theme by default — `colors.blu` (typo) is a compile error. Custom `kbach.config.js` colors aren't visible to TypeScript (runtime-loaded plain `.js`), so either widen per call — `useColors<DefaultColorName | 'brand'>()` — or, better, augment once project-wide in any `.d.ts` your tsconfig includes:
+Typed against the built-in theme by default — `colors.blu` (typo) is a compile error. Custom `kbach.config.js` colors work too, with **zero setup**: the Vite plugin (and `@kbach/native`'s Babel plugin) automatically generate a `kbach-types.d.ts` next to your config, kept in sync every time the dev server / Metro picks up an edit to it — safe to add to `.gitignore`. `useColors()`/`useSpacing()` see your custom names immediately, no type parameter needed, same typo-catching as the built-in ones.
+
+If you'd rather commit the types instead of generating them (a library package with no dev server/bundler step of its own, for instance), hand-author the same thing in any `.d.ts` your tsconfig includes:
 
 ```ts
 import '@kbach/react'; // or '@kbach/native' — either works, native re-exports react's types
@@ -199,9 +201,12 @@ declare module '@kbach/react' {
     accent: string;    // a flat color, like the built-in white/black — also what a
                         // mode-aware { light, dark } config color resolves to at read time
   }
+  interface KbachCustomSpacing {
+    18: true; // only the key is read — value is just a placeholder
+  }
 }
 ```
-Every `useColors()` call in the project then sees `brand`/`accent` automatically, no type parameter needed — same typo-catching as the built-in names. `useSpacing()` has the equivalent `KbachCustomSpacing` interface (`interface KbachCustomSpacing { 18: true }` — only the key is read) for the spacing scale (`spacing[4]` → `16`, `spacing.full` → `'100%'`).
+A hand-authored file and the generated one both merge into the exact same interfaces, so either — or both at once — works.
 
 ---
 
@@ -735,17 +740,21 @@ extend: {
       surface: { light: '#ffffff', dark: '#111827' },
       // each side can itself be an alias — resolved independently
       accent:  { light: 'blue-6', dark: 'blue-4' },
+      // or derived from another color at an opacity — 'name/opacity', resolved
+      // once here instead of only being computable at runtime via colors.alpha()
+      accentSoft: { light: 'accent/30', dark: 'accent/40' },
     },
   },
 },
 ```
 
 ```jsx
-<div className="bg-surface text-accent" />
-// equivalent to writing bg-white dark:bg-gray-9 text-blue-6 dark:text-blue-4 by hand
+<div className="bg-surface text-accent hover:bg-accentSoft" />
+// equivalent to writing bg-white dark:bg-gray-9 text-blue-6 dark:text-blue-4
+// hover:bg-[rgba(...)] dark:hover:bg-[rgba(...)] by hand
 ```
 
-Works everywhere a color does — `useColors()` (returns the active side directly), opacity composition (`bg-surface/50`), and per-shade within a scale (`brand: { 6: { light: '#3b82f6', dark: '#60a5fa' } }`). An explicit `dark:`/`light:` modifier stacked on an already mode-aware color is not supported (falls back to the light side) — the whole point is not needing `dark:` for these.
+Works everywhere a color does — `useColors()` (returns the active side directly), opacity composition (`bg-surface/50`), per-shade within a scale (`brand: { 6: { light: '#3b82f6', dark: '#60a5fa' } }`), and stacked under an explicit modifier (`dark:hover:bg-accent` correctly uses the dark side, still scoped to dark mode + hover — the modifier doesn't need to be there in the first place, but it's respected if it is).
 
 ### Runtime update
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbach/react",
-  "version": "0.6.35",
+  "version": "0.6.37",
   "description": "React / React Native components and hooks for the Kbach framework",
   "repository": {
     "type": "git",