@ankhorage/zora 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.12.0
+
+### Minor Changes
+
+- 7279fe4: Derives light and dark primary colors from a single ZORA theme seed using an internal OKLCH color boundary.
+
 ## 0.11.0
 
 ### Minor Changes

package/README.md

@@ -90,6 +90,22 @@ export function App({ appTheme }: { appTheme: ZoraTheme }) {
 }
 ```
 
+ZORA themes use a single seed `primaryColor`. ZORA derives mode-specific primary
+colors for light and dark mode internally.
+
+```tsx
+<ZoraProvider
+  theme={{
+    id: 'studio',
+    primaryColor: '#0f766e',
+    harmony: 'analogous',
+    tone: 'jewel',
+  }}
+>
+  <App />
+</ZoraProvider>
+```
+
 `mode` and `themeId` are available on public ZORA components through `ZoraBaseProps`.
 Use component props for local component/subtree overrides.
 

package/dist/internal/color/index.d.ts

@@ -0,0 +1,3 @@
+export { parseHexToOklch } from './oklch';
+export { resolveModePrimaryColor } from './primary';
+//# sourceMappingURL=index.d.ts.map

package/dist/internal/color/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/internal/color/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC"}

package/dist/internal/color/index.js

@@ -0,0 +1,3 @@
+export { parseHexToOklch } from './oklch';
+export { resolveModePrimaryColor } from './primary';
+//# sourceMappingURL=index.js.map

package/dist/internal/color/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/internal/color/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC","sourcesContent":["export { parseHexToOklch } from './oklch';\nexport { resolveModePrimaryColor } from './primary';\n"]}

package/dist/internal/color/oklch.d.ts

@@ -0,0 +1,6 @@
+import type { ZoraHexColor } from '../../theme/types';
+import type { ZoraOklchColor } from './types';
+export declare function parseHexToOklch(hex: ZoraHexColor): ZoraOklchColor;
+export declare function formatOklchAsHex(color: ZoraOklchColor): ZoraHexColor;
+export declare function clampOklchToGamut(color: ZoraOklchColor): ZoraOklchColor;
+//# sourceMappingURL=oklch.d.ts.map

package/dist/internal/color/oklch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oklch.d.ts","sourceRoot":"","sources":["../../../src/internal/color/oklch.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAc9C,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,cAAc,CAoBjE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,CAcpE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,cAAc,GAAG,cAAc,CAavE"}

package/dist/internal/color/oklch.js

@@ -0,0 +1,53 @@
+import { converter, formatHex, parse, toGamut } from 'culori';
+const toOklch = converter('oklch');
+const gamutMapToSrgb = toGamut('rgb', 'oklch');
+function normalizeHueDegrees(hue) {
+    const normalized = ((hue % 360) + 360) % 360;
+    return normalized;
+}
+function isSixDigitHexColor(value) {
+    return /^#[0-9a-fA-F]{6}$/.test(value);
+}
+export function parseHexToOklch(hex) {
+    if (!isSixDigitHexColor(hex)) {
+        throw new Error(`Expected a 6-digit hex color like '#0f766e', got '${String(hex)}'.`);
+    }
+    const parsed = parse(hex);
+    if (!parsed) {
+        throw new Error(`Unable to parse hex color '${String(hex)}'.`);
+    }
+    const oklch = toOklch(parsed);
+    if (typeof oklch.l !== 'number' || typeof oklch.c !== 'number') {
+        throw new Error(`Unable to convert hex color '${String(hex)}' to OKLCH.`);
+    }
+    return {
+        l: oklch.l,
+        c: oklch.c,
+        h: normalizeHueDegrees(typeof oklch.h === 'number' ? oklch.h : 0),
+    };
+}
+export function formatOklchAsHex(color) {
+    const mapped = gamutMapToSrgb({ mode: 'oklch', l: color.l, c: color.c, h: color.h });
+    const hex = formatHex(mapped);
+    if (!hex || !isSixDigitHexColor(hex)) {
+        throw new Error('Unable to format OKLCH color as a 6-digit hex value.');
+    }
+    const normalized = hex.toLowerCase();
+    if (!isSixDigitHexColor(normalized)) {
+        throw new Error('Unable to format OKLCH color as a 6-digit hex value.');
+    }
+    return normalized;
+}
+export function clampOklchToGamut(color) {
+    const mapped = gamutMapToSrgb({ mode: 'oklch', l: color.l, c: color.c, h: color.h });
+    const clamped = toOklch(mapped);
+    if (typeof clamped.l !== 'number' || typeof clamped.c !== 'number') {
+        throw new Error('Unable to clamp OKLCH color to sRGB gamut.');
+    }
+    return {
+        l: clamped.l,
+        c: clamped.c,
+        h: normalizeHueDegrees(typeof clamped.h === 'number' ? clamped.h : 0),
+    };
+}
+//# sourceMappingURL=oklch.js.map

package/dist/internal/color/oklch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oklch.js","sourceRoot":"","sources":["../../../src/internal/color/oklch.ts"],"names":[],"mappings":"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","sourcesContent":["import { converter, formatHex, parse, toGamut } from 'culori';\n\nimport type { ZoraHexColor } from '../../theme/types';\nimport type { ZoraOklchColor } from './types';\n\nconst toOklch = converter('oklch');\nconst gamutMapToSrgb = toGamut('rgb', 'oklch');\n\nfunction normalizeHueDegrees(hue: number): number {\n  const normalized = ((hue % 360) + 360) % 360;\n  return normalized;\n}\n\nfunction isSixDigitHexColor(value: string): value is ZoraHexColor {\n  return /^#[0-9a-fA-F]{6}$/.test(value);\n}\n\nexport function parseHexToOklch(hex: ZoraHexColor): ZoraOklchColor {\n  if (!isSixDigitHexColor(hex)) {\n    throw new Error(`Expected a 6-digit hex color like '#0f766e', got '${String(hex)}'.`);\n  }\n\n  const parsed = parse(hex);\n  if (!parsed) {\n    throw new Error(`Unable to parse hex color '${String(hex)}'.`);\n  }\n\n  const oklch = toOklch(parsed);\n  if (typeof oklch.l !== 'number' || typeof oklch.c !== 'number') {\n    throw new Error(`Unable to convert hex color '${String(hex)}' to OKLCH.`);\n  }\n\n  return {\n    l: oklch.l,\n    c: oklch.c,\n    h: normalizeHueDegrees(typeof oklch.h === 'number' ? oklch.h : 0),\n  };\n}\n\nexport function formatOklchAsHex(color: ZoraOklchColor): ZoraHexColor {\n  const mapped = gamutMapToSrgb({ mode: 'oklch', l: color.l, c: color.c, h: color.h });\n  const hex = formatHex(mapped);\n\n  if (!hex || !isSixDigitHexColor(hex)) {\n    throw new Error('Unable to format OKLCH color as a 6-digit hex value.');\n  }\n\n  const normalized = hex.toLowerCase();\n  if (!isSixDigitHexColor(normalized)) {\n    throw new Error('Unable to format OKLCH color as a 6-digit hex value.');\n  }\n\n  return normalized;\n}\n\nexport function clampOklchToGamut(color: ZoraOklchColor): ZoraOklchColor {\n  const mapped = gamutMapToSrgb({ mode: 'oklch', l: color.l, c: color.c, h: color.h });\n  const clamped = toOklch(mapped);\n\n  if (typeof clamped.l !== 'number' || typeof clamped.c !== 'number') {\n    throw new Error('Unable to clamp OKLCH color to sRGB gamut.');\n  }\n\n  return {\n    l: clamped.l,\n    c: clamped.c,\n    h: normalizeHueDegrees(typeof clamped.h === 'number' ? clamped.h : 0),\n  };\n}\n"]}

package/dist/internal/color/primary.d.ts

@@ -0,0 +1,3 @@
+import type { ZoraHexColor, ZoraThemeMode } from '../../theme/types';
+export declare function resolveModePrimaryColor(primaryColor: ZoraHexColor, mode: ZoraThemeMode): ZoraHexColor;
+//# sourceMappingURL=primary.d.ts.map

package/dist/internal/color/primary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primary.d.ts","sourceRoot":"","sources":["../../../src/internal/color/primary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AA2BrE,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,YAAY,EAC1B,IAAI,EAAE,aAAa,GAClB,YAAY,CAiCd"}

package/dist/internal/color/primary.js

@@ -0,0 +1,44 @@
+import { clampOklchToGamut, formatOklchAsHex, parseHexToOklch } from './oklch';
+const FALLBACK_PRIMARY_COLOR = '#0f766e';
+const LIGHT_PRIMARY_LIGHTNESS_TARGET = 0.52;
+const DARK_PRIMARY_LIGHTNESS_TARGET = 0.72;
+const MIN_PRIMARY_CHROMA = 0.04;
+const MAX_LIGHT_PRIMARY_CHROMA = 0.18;
+const MAX_DARK_PRIMARY_CHROMA = 0.2;
+const LIGHTNESS_BLEND = 0.85;
+function clampNumber(value, min, max) {
+    return Math.max(min, Math.min(value, max));
+}
+function resolveModePrimaryTargetLightness(mode) {
+    return mode === 'dark' ? DARK_PRIMARY_LIGHTNESS_TARGET : LIGHT_PRIMARY_LIGHTNESS_TARGET;
+}
+function resolveModePrimaryMaxChroma(mode) {
+    return mode === 'dark' ? MAX_DARK_PRIMARY_CHROMA : MAX_LIGHT_PRIMARY_CHROMA;
+}
+export function resolveModePrimaryColor(primaryColor, mode) {
+    let seed;
+    try {
+        seed = parseHexToOklch(primaryColor);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (process.env.NODE_ENV === 'production') {
+            console.warn(`Invalid ZORA primaryColor '${primaryColor}'. Falling back. ${message}`);
+            return resolveModePrimaryColor(FALLBACK_PRIMARY_COLOR, mode);
+        }
+        throw error instanceof Error ? error : new Error(message);
+    }
+    const targetLightness = resolveModePrimaryTargetLightness(mode);
+    const maxChroma = resolveModePrimaryMaxChroma(mode);
+    const blendedLightness = seed.l + (targetLightness - seed.l) * LIGHTNESS_BLEND;
+    const boundedLightness = clampNumber(blendedLightness, 0.12, 0.92);
+    const cappedChroma = clampNumber(seed.c, 0, maxChroma);
+    const boundedChroma = seed.c < MIN_PRIMARY_CHROMA ? cappedChroma : Math.max(cappedChroma, MIN_PRIMARY_CHROMA);
+    const derived = clampOklchToGamut({
+        l: boundedLightness,
+        c: boundedChroma,
+        h: seed.h,
+    });
+    return formatOklchAsHex(derived);
+}
+//# sourceMappingURL=primary.js.map

package/dist/internal/color/primary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primary.js","sourceRoot":"","sources":["../../../src/internal/color/primary.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAG/E,MAAM,sBAAsB,GAAiB,SAAS,CAAC;AAEvD,MAAM,8BAA8B,GAAG,IAAI,CAAC;AAC5C,MAAM,6BAA6B,GAAG,IAAI,CAAC;AAE3C,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAChC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AACtC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAEpC,MAAM,eAAe,GAAG,IAAI,CAAC;AAE7B,SAAS,WAAW,CAAC,KAAa,EAAE,GAAW,EAAE,GAAW;IAC1D,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,iCAAiC,CAAC,IAAmB;IAC5D,OAAO,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,8BAA8B,CAAC;AAC1F,CAAC;AAED,SAAS,2BAA2B,CAAC,IAAmB;IACtD,OAAO,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,wBAAwB,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,YAA0B,EAC1B,IAAmB;IAEnB,IAAI,IAAoB,CAAC;IAEzB,IAAI,CAAC;QACH,IAAI,GAAG,eAAe,CAAC,YAAY,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAEvE,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;YAC1C,OAAO,CAAC,IAAI,CAAC,8BAA8B,YAAY,oBAAoB,OAAO,EAAE,CAAC,CAAC;YACtF,OAAO,uBAAuB,CAAC,sBAAsB,EAAE,IAAI,CAAC,CAAC;QAC/D,CAAC;QAED,MAAM,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,eAAe,GAAG,iCAAiC,CAAC,IAAI,CAAC,CAAC;IAChE,MAAM,SAAS,GAAG,2BAA2B,CAAC,IAAI,CAAC,CAAC;IAEpD,MAAM,gBAAgB,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC;IAC/E,MAAM,gBAAgB,GAAG,WAAW,CAAC,gBAAgB,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAEnE,MAAM,YAAY,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC;IACvD,MAAM,aAAa,GACjB,IAAI,CAAC,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,kBAAkB,CAAC,CAAC;IAE1F,MAAM,OAAO,GAAG,iBAAiB,CAAC;QAChC,CAAC,EAAE,gBAAgB;QACnB,CAAC,EAAE,aAAa;QAChB,CAAC,EAAE,IAAI,CAAC,CAAC;KACV,CAAC,CAAC;IAEH,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC;AACnC,CAAC","sourcesContent":["import type { ZoraHexColor, ZoraThemeMode } from '../../theme/types';\nimport { clampOklchToGamut, formatOklchAsHex, parseHexToOklch } from './oklch';\nimport type { ZoraOklchColor } from './types';\n\nconst FALLBACK_PRIMARY_COLOR: ZoraHexColor = '#0f766e';\n\nconst LIGHT_PRIMARY_LIGHTNESS_TARGET = 0.52;\nconst DARK_PRIMARY_LIGHTNESS_TARGET = 0.72;\n\nconst MIN_PRIMARY_CHROMA = 0.04;\nconst MAX_LIGHT_PRIMARY_CHROMA = 0.18;\nconst MAX_DARK_PRIMARY_CHROMA = 0.2;\n\nconst LIGHTNESS_BLEND = 0.85;\n\nfunction clampNumber(value: number, min: number, max: number): number {\n  return Math.max(min, Math.min(value, max));\n}\n\nfunction resolveModePrimaryTargetLightness(mode: ZoraThemeMode): number {\n  return mode === 'dark' ? DARK_PRIMARY_LIGHTNESS_TARGET : LIGHT_PRIMARY_LIGHTNESS_TARGET;\n}\n\nfunction resolveModePrimaryMaxChroma(mode: ZoraThemeMode): number {\n  return mode === 'dark' ? MAX_DARK_PRIMARY_CHROMA : MAX_LIGHT_PRIMARY_CHROMA;\n}\n\nexport function resolveModePrimaryColor(\n  primaryColor: ZoraHexColor,\n  mode: ZoraThemeMode,\n): ZoraHexColor {\n  let seed: ZoraOklchColor;\n\n  try {\n    seed = parseHexToOklch(primaryColor);\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n\n    if (process.env.NODE_ENV === 'production') {\n      console.warn(`Invalid ZORA primaryColor '${primaryColor}'. Falling back. ${message}`);\n      return resolveModePrimaryColor(FALLBACK_PRIMARY_COLOR, mode);\n    }\n\n    throw error instanceof Error ? error : new Error(message);\n  }\n\n  const targetLightness = resolveModePrimaryTargetLightness(mode);\n  const maxChroma = resolveModePrimaryMaxChroma(mode);\n\n  const blendedLightness = seed.l + (targetLightness - seed.l) * LIGHTNESS_BLEND;\n  const boundedLightness = clampNumber(blendedLightness, 0.12, 0.92);\n\n  const cappedChroma = clampNumber(seed.c, 0, maxChroma);\n  const boundedChroma =\n    seed.c < MIN_PRIMARY_CHROMA ? cappedChroma : Math.max(cappedChroma, MIN_PRIMARY_CHROMA);\n\n  const derived = clampOklchToGamut({\n    l: boundedLightness,\n    c: boundedChroma,\n    h: seed.h,\n  });\n\n  return formatOklchAsHex(derived);\n}\n"]}

package/dist/internal/color/types.d.ts

@@ -0,0 +1,6 @@
+export interface ZoraOklchColor {
+    l: number;
+    c: number;
+    h: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/internal/color/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/internal/color/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX"}

package/dist/internal/color/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/internal/color/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/internal/color/types.ts"],"names":[],"mappings":"","sourcesContent":["export interface ZoraOklchColor {\n  l: number;\n  c: number;\n  h: number;\n}\n"]}

package/dist/theme/createZoraThemeConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createZoraThemeConfig.d.ts","sourceRoot":"","sources":["../../src/theme/createZoraThemeConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAAgB,SAAS,EAAiB,MAAM,SAAS,CAAC;AAStE,wBAAgB,qBAAqB,CAAC,KAAK,GAAE,SAA4B,GAAG,WAAW,CAetF"}
+{"version":3,"file":"createZoraThemeConfig.d.ts","sourceRoot":"","sources":["../../src/theme/createZoraThemeConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGzC,wBAAgB,qBAAqB,CAAC,KAAK,GAAE,SAA4B,GAAG,WAAW,CAetF"}

package/dist/theme/createZoraThemeConfig.js

@@ -1,9 +1,5 @@
+import { resolveModePrimaryColor } from '../internal/color';
 import { zoraDefaultTheme } from './zoraDefaultTheme';
-function resolveModePrimaryColor(primaryColor, _mode) {
-    // Intentionally conservative in Plan 1: mode-specific primary derivation
-    // (OKLCH/lightness scale, etc.) comes in later theme-engine work.
-    return primaryColor;
-}
 export function createZoraThemeConfig(theme = zoraDefaultTheme) {
     return {
         id: theme.id,

package/dist/theme/createZoraThemeConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"createZoraThemeConfig.js","sourceRoot":"","sources":["../../src/theme/createZoraThemeConfig.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,SAAS,uBAAuB,CAAC,YAA0B,EAAE,KAAoB;IAC/E,yEAAyE;IACzE,kEAAkE;IAClE,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,QAAmB,gBAAgB;IACvE,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,EAAE;QAC5B,KAAK,EAAE;YACL,YAAY,EAAE,uBAAuB,CAAC,KAAK,CAAC,YAAY,EAAE,OAAO,CAAC;YAClE,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,UAAU,EAAE,KAAK,CAAC,IAAI;SACvB;QACD,IAAI,EAAE;YACJ,YAAY,EAAE,uBAAuB,CAAC,KAAK,CAAC,YAAY,EAAE,MAAM,CAAC;YACjE,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,UAAU,EAAE,KAAK,CAAC,IAAI;SACvB;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type { ThemeConfig } from '@ankhorage/surface';\n\nimport type { ZoraHexColor, ZoraTheme, ZoraThemeMode } from './types';\nimport { zoraDefaultTheme } from './zoraDefaultTheme';\n\nfunction resolveModePrimaryColor(primaryColor: ZoraHexColor, _mode: ZoraThemeMode): ZoraHexColor {\n  // Intentionally conservative in Plan 1: mode-specific primary derivation\n  // (OKLCH/lightness scale, etc.) comes in later theme-engine work.\n  return primaryColor;\n}\n\nexport function createZoraThemeConfig(theme: ZoraTheme = zoraDefaultTheme): ThemeConfig {\n  return {\n    id: theme.id,\n    name: theme.name ?? theme.id,\n    light: {\n      primaryColor: resolveModePrimaryColor(theme.primaryColor, 'light'),\n      harmony: theme.harmony,\n      systemTone: theme.tone,\n    },\n    dark: {\n      primaryColor: resolveModePrimaryColor(theme.primaryColor, 'dark'),\n      harmony: theme.harmony,\n      systemTone: theme.tone,\n    },\n  };\n}\n"]}
+{"version":3,"file":"createZoraThemeConfig.js","sourceRoot":"","sources":["../../src/theme/createZoraThemeConfig.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,UAAU,qBAAqB,CAAC,QAAmB,gBAAgB;IACvE,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,EAAE;QAC5B,KAAK,EAAE;YACL,YAAY,EAAE,uBAAuB,CAAC,KAAK,CAAC,YAAY,EAAE,OAAO,CAAC;YAClE,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,UAAU,EAAE,KAAK,CAAC,IAAI;SACvB;QACD,IAAI,EAAE;YACJ,YAAY,EAAE,uBAAuB,CAAC,KAAK,CAAC,YAAY,EAAE,MAAM,CAAC;YACjE,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,UAAU,EAAE,KAAK,CAAC,IAAI;SACvB;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type { ThemeConfig } from '@ankhorage/surface';\n\nimport { resolveModePrimaryColor } from '../internal/color';\nimport type { ZoraTheme } from './types';\nimport { zoraDefaultTheme } from './zoraDefaultTheme';\n\nexport function createZoraThemeConfig(theme: ZoraTheme = zoraDefaultTheme): ThemeConfig {\n  return {\n    id: theme.id,\n    name: theme.name ?? theme.id,\n    light: {\n      primaryColor: resolveModePrimaryColor(theme.primaryColor, 'light'),\n      harmony: theme.harmony,\n      systemTone: theme.tone,\n    },\n    dark: {\n      primaryColor: resolveModePrimaryColor(theme.primaryColor, 'dark'),\n      harmony: theme.harmony,\n      systemTone: theme.tone,\n    },\n  };\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/zora",
   "type": "module",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Opinionated React Native and React Native Web UI kit built on @ankhorage/surface.",
   "homepage": "https://github.com/ankhorage/zora#readme",
   "bugs": {
@@ -43,7 +43,8 @@
     }
   },
   "dependencies": {
-    "@ankhorage/surface": "^0.1.12"
+    "@ankhorage/surface": "^0.1.12",
+    "culori": "^4.0.2"
   },
   "files": [
     "dist",
@@ -84,6 +85,7 @@
     "@changesets/cli": "^2.31.0",
     "@expo/vector-icons": "^15.1.1",
     "@react-native-picker/picker": "^2.11.4",
+    "@types/culori": "^4.0.1",
     "@types/bun": "^1.3.13",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",

package/src/internal/color/index.ts

@@ -0,0 +1,2 @@
+export { parseHexToOklch } from './oklch';
+export { resolveModePrimaryColor } from './primary';

package/src/internal/color/oklch.ts

@@ -0,0 +1,69 @@
+import { converter, formatHex, parse, toGamut } from 'culori';
+
+import type { ZoraHexColor } from '../../theme/types';
+import type { ZoraOklchColor } from './types';
+
+const toOklch = converter('oklch');
+const gamutMapToSrgb = toGamut('rgb', 'oklch');
+
+function normalizeHueDegrees(hue: number): number {
+  const normalized = ((hue % 360) + 360) % 360;
+  return normalized;
+}
+
+function isSixDigitHexColor(value: string): value is ZoraHexColor {
+  return /^#[0-9a-fA-F]{6}$/.test(value);
+}
+
+export function parseHexToOklch(hex: ZoraHexColor): ZoraOklchColor {
+  if (!isSixDigitHexColor(hex)) {
+    throw new Error(`Expected a 6-digit hex color like '#0f766e', got '${String(hex)}'.`);
+  }
+
+  const parsed = parse(hex);
+  if (!parsed) {
+    throw new Error(`Unable to parse hex color '${String(hex)}'.`);
+  }
+
+  const oklch = toOklch(parsed);
+  if (typeof oklch.l !== 'number' || typeof oklch.c !== 'number') {
+    throw new Error(`Unable to convert hex color '${String(hex)}' to OKLCH.`);
+  }
+
+  return {
+    l: oklch.l,
+    c: oklch.c,
+    h: normalizeHueDegrees(typeof oklch.h === 'number' ? oklch.h : 0),
+  };
+}
+
+export function formatOklchAsHex(color: ZoraOklchColor): ZoraHexColor {
+  const mapped = gamutMapToSrgb({ mode: 'oklch', l: color.l, c: color.c, h: color.h });
+  const hex = formatHex(mapped);
+
+  if (!hex || !isSixDigitHexColor(hex)) {
+    throw new Error('Unable to format OKLCH color as a 6-digit hex value.');
+  }
+
+  const normalized = hex.toLowerCase();
+  if (!isSixDigitHexColor(normalized)) {
+    throw new Error('Unable to format OKLCH color as a 6-digit hex value.');
+  }
+
+  return normalized;
+}
+
+export function clampOklchToGamut(color: ZoraOklchColor): ZoraOklchColor {
+  const mapped = gamutMapToSrgb({ mode: 'oklch', l: color.l, c: color.c, h: color.h });
+  const clamped = toOklch(mapped);
+
+  if (typeof clamped.l !== 'number' || typeof clamped.c !== 'number') {
+    throw new Error('Unable to clamp OKLCH color to sRGB gamut.');
+  }
+
+  return {
+    l: clamped.l,
+    c: clamped.c,
+    h: normalizeHueDegrees(typeof clamped.h === 'number' ? clamped.h : 0),
+  };
+}

package/src/internal/color/primary.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { ZoraHexColor } from '../../theme/types';
+import { parseHexToOklch } from './oklch';
+import { resolveModePrimaryColor } from './primary';
+
+function isSixDigitHexColor(value: string): value is ZoraHexColor {
+  return /^#[0-9a-f]{6}$/.test(value);
+}
+
+function hueDeltaDegrees(a: number, b: number): number {
+  const raw = Math.abs(a - b) % 360;
+  return Math.min(raw, 360 - raw);
+}
+
+describe('resolveModePrimaryColor', () => {
+  test('returns valid hex for light and dark mode', () => {
+    const seed: ZoraHexColor = '#0f766e';
+
+    const light = resolveModePrimaryColor(seed, 'light');
+    const dark = resolveModePrimaryColor(seed, 'dark');
+
+    expect(isSixDigitHexColor(light)).toBe(true);
+    expect(isSixDigitHexColor(dark)).toBe(true);
+  });
+
+  test('derives different colors for light vs dark for a typical saturated seed', () => {
+    const seed: ZoraHexColor = '#0f766e';
+
+    const light = resolveModePrimaryColor(seed, 'light');
+    const dark = resolveModePrimaryColor(seed, 'dark');
+
+    expect(light).not.toBe(dark);
+  });
+
+  test('dark derived primary has higher OKLCH lightness than the light derived primary', () => {
+    const seed: ZoraHexColor = '#0f766e';
+
+    const light = resolveModePrimaryColor(seed, 'light');
+    const dark = resolveModePrimaryColor(seed, 'dark');
+
+    const lightOklch = parseHexToOklch(light);
+    const darkOklch = parseHexToOklch(dark);
+
+    expect(darkOklch.l).toBeGreaterThan(lightOklch.l);
+  });
+
+  test('preserves hue approximately for a non-neutral seed', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const seedOklch = parseHexToOklch(seed);
+
+    const light = resolveModePrimaryColor(seed, 'light');
+    const dark = resolveModePrimaryColor(seed, 'dark');
+
+    const lightOklch = parseHexToOklch(light);
+    const darkOklch = parseHexToOklch(dark);
+
+    expect(hueDeltaDegrees(seedOklch.h, lightOklch.h)).toBeLessThan(20);
+    expect(hueDeltaDegrees(seedOklch.h, darkOklch.h)).toBeLessThan(20);
+  });
+
+  test('bounds chroma', () => {
+    const seed: ZoraHexColor = '#ff00ff';
+
+    const light = resolveModePrimaryColor(seed, 'light');
+    const dark = resolveModePrimaryColor(seed, 'dark');
+
+    const lightOklch = parseHexToOklch(light);
+    const darkOklch = parseHexToOklch(dark);
+
+    expect(lightOklch.c).toBeLessThanOrEqual(0.18 + 0.01);
+    expect(darkOklch.c).toBeLessThanOrEqual(0.2 + 0.01);
+  });
+
+  test('handles low-chroma colors without crashing', () => {
+    const seed: ZoraHexColor = '#808080';
+
+    const light = resolveModePrimaryColor(seed, 'light');
+    const dark = resolveModePrimaryColor(seed, 'dark');
+
+    expect(isSixDigitHexColor(light)).toBe(true);
+    expect(isSixDigitHexColor(dark)).toBe(true);
+  });
+
+  test('throws on invalid hex in test/development', () => {
+    const invalid: ZoraHexColor = '#nope';
+
+    expect(() => resolveModePrimaryColor(invalid, 'light')).toThrow();
+  });
+
+  test('falls back in production when input is invalid', () => {
+    const invalid: ZoraHexColor = '#nope';
+
+    const originalEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = 'production';
+
+    try {
+      const resolved = resolveModePrimaryColor(invalid, 'light');
+      expect(resolved).not.toBe('#0f766e');
+      expect(resolved).toBe(resolveModePrimaryColor('#0f766e', 'light'));
+    } finally {
+      process.env.NODE_ENV = originalEnv;
+    }
+  });
+});

package/src/internal/color/primary.ts

@@ -0,0 +1,64 @@
+import type { ZoraHexColor, ZoraThemeMode } from '../../theme/types';
+import { clampOklchToGamut, formatOklchAsHex, parseHexToOklch } from './oklch';
+import type { ZoraOklchColor } from './types';
+
+const FALLBACK_PRIMARY_COLOR: ZoraHexColor = '#0f766e';
+
+const LIGHT_PRIMARY_LIGHTNESS_TARGET = 0.52;
+const DARK_PRIMARY_LIGHTNESS_TARGET = 0.72;
+
+const MIN_PRIMARY_CHROMA = 0.04;
+const MAX_LIGHT_PRIMARY_CHROMA = 0.18;
+const MAX_DARK_PRIMARY_CHROMA = 0.2;
+
+const LIGHTNESS_BLEND = 0.85;
+
+function clampNumber(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(value, max));
+}
+
+function resolveModePrimaryTargetLightness(mode: ZoraThemeMode): number {
+  return mode === 'dark' ? DARK_PRIMARY_LIGHTNESS_TARGET : LIGHT_PRIMARY_LIGHTNESS_TARGET;
+}
+
+function resolveModePrimaryMaxChroma(mode: ZoraThemeMode): number {
+  return mode === 'dark' ? MAX_DARK_PRIMARY_CHROMA : MAX_LIGHT_PRIMARY_CHROMA;
+}
+
+export function resolveModePrimaryColor(
+  primaryColor: ZoraHexColor,
+  mode: ZoraThemeMode,
+): ZoraHexColor {
+  let seed: ZoraOklchColor;
+
+  try {
+    seed = parseHexToOklch(primaryColor);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+
+    if (process.env.NODE_ENV === 'production') {
+      console.warn(`Invalid ZORA primaryColor '${primaryColor}'. Falling back. ${message}`);
+      return resolveModePrimaryColor(FALLBACK_PRIMARY_COLOR, mode);
+    }
+
+    throw error instanceof Error ? error : new Error(message);
+  }
+
+  const targetLightness = resolveModePrimaryTargetLightness(mode);
+  const maxChroma = resolveModePrimaryMaxChroma(mode);
+
+  const blendedLightness = seed.l + (targetLightness - seed.l) * LIGHTNESS_BLEND;
+  const boundedLightness = clampNumber(blendedLightness, 0.12, 0.92);
+
+  const cappedChroma = clampNumber(seed.c, 0, maxChroma);
+  const boundedChroma =
+    seed.c < MIN_PRIMARY_CHROMA ? cappedChroma : Math.max(cappedChroma, MIN_PRIMARY_CHROMA);
+
+  const derived = clampOklchToGamut({
+    l: boundedLightness,
+    c: boundedChroma,
+    h: seed.h,
+  });
+
+  return formatOklchAsHex(derived);
+}

package/src/internal/color/types.ts

@@ -0,0 +1,5 @@
+export interface ZoraOklchColor {
+  l: number;
+  c: number;
+  h: number;
+}

package/src/theme/createZoraThemeConfig.test.ts

@@ -1,6 +1,12 @@
 import { describe, expect, test } from 'bun:test';
 
+import { parseHexToOklch } from '../internal/color';
 import { createZoraThemeConfig } from './createZoraThemeConfig';
+import type { ZoraHexColor } from './types';
+
+function isSixDigitHexColor(value: string): value is ZoraHexColor {
+  return /^#[0-9a-f]{6}$/.test(value);
+}
 
 describe('createZoraThemeConfig', () => {
   test('converts the default theme seed into a surface config', () => {
@@ -8,12 +14,18 @@ describe('createZoraThemeConfig', () => {
 
     expect(themeConfig.id).toBe('zora');
     expect(themeConfig.name).toBe('ZORA');
-    expect(themeConfig.light.primaryColor).toBe('#0f766e');
+    expect(isSixDigitHexColor(themeConfig.light.primaryColor)).toBe(true);
     expect(themeConfig.light.harmony).toBe('analogous');
     expect(themeConfig.light.systemTone).toBe('jewel');
-    expect(themeConfig.dark.primaryColor).toBe('#0f766e');
+    expect(isSixDigitHexColor(themeConfig.dark.primaryColor)).toBe(true);
     expect(themeConfig.dark.harmony).toBe('analogous');
     expect(themeConfig.dark.systemTone).toBe('jewel');
+
+    expect(themeConfig.light.primaryColor).not.toBe(themeConfig.dark.primaryColor);
+
+    const lightOklch = parseHexToOklch(themeConfig.light.primaryColor);
+    const darkOklch = parseHexToOklch(themeConfig.dark.primaryColor);
+    expect(darkOklch.l).toBeGreaterThan(lightOklch.l);
   });
 
   test('falls back to id when name is omitted', () => {
@@ -26,11 +38,13 @@ describe('createZoraThemeConfig', () => {
 
     expect(themeConfig.id).toBe('studio');
     expect(themeConfig.name).toBe('studio');
-    expect(themeConfig.light.primaryColor).toBe('#0f766e');
+    expect(isSixDigitHexColor(themeConfig.light.primaryColor)).toBe(true);
     expect(themeConfig.light.harmony).toBe('analogous');
     expect(themeConfig.light.systemTone).toBe('jewel');
-    expect(themeConfig.dark.primaryColor).toBe('#0f766e');
+    expect(isSixDigitHexColor(themeConfig.dark.primaryColor)).toBe(true);
     expect(themeConfig.dark.harmony).toBe('analogous');
     expect(themeConfig.dark.systemTone).toBe('jewel');
+
+    expect(themeConfig.light.primaryColor).not.toBe(themeConfig.dark.primaryColor);
   });
 });

package/src/theme/createZoraThemeConfig.ts

@@ -1,14 +1,9 @@
 import type { ThemeConfig } from '@ankhorage/surface';
 
-import type { ZoraHexColor, ZoraTheme, ZoraThemeMode } from './types';
+import { resolveModePrimaryColor } from '../internal/color';
+import type { ZoraTheme } from './types';
 import { zoraDefaultTheme } from './zoraDefaultTheme';
 
-function resolveModePrimaryColor(primaryColor: ZoraHexColor, _mode: ZoraThemeMode): ZoraHexColor {
-  // Intentionally conservative in Plan 1: mode-specific primary derivation
-  // (OKLCH/lightness scale, etc.) comes in later theme-engine work.
-  return primaryColor;
-}
-
 export function createZoraThemeConfig(theme: ZoraTheme = zoraDefaultTheme): ThemeConfig {
   return {
     id: theme.id,