@ankhorage/zora 0.11.0 → 0.12.1

package/src/internal/color/scales.ts

@@ -0,0 +1,145 @@
+import type { ZoraHexColor } from '../../theme/types';
+import { clampOklchToGamut, formatOklchAsHex, parseHexToOklch } from './oklch';
+import { type ZoraColorScale, type ZoraColorScaleStep } from './types';
+
+export interface CreateZoraColorScaleOptions {
+  seed: ZoraHexColor;
+  role?: 'primary' | 'neutral';
+}
+
+const PRIMARY_LIGHTNESS_BY_STEP: Record<ZoraColorScaleStep, number> = {
+  50: 0.97,
+  100: 0.93,
+  200: 0.86,
+  300: 0.78,
+  400: 0.68,
+  500: 0.58,
+  600: 0.5,
+  700: 0.42,
+  800: 0.34,
+  900: 0.27,
+  950: 0.2,
+};
+
+const NEUTRAL_LIGHTNESS_BY_STEP: Record<ZoraColorScaleStep, number> = {
+  50: 0.98,
+  100: 0.95,
+  200: 0.89,
+  300: 0.8,
+  400: 0.68,
+  500: 0.55,
+  600: 0.44,
+  700: 0.34,
+  800: 0.25,
+  900: 0.18,
+  950: 0.12,
+};
+
+const PRIMARY_CHROMA_MULTIPLIER_BY_STEP: Record<ZoraColorScaleStep, number> = {
+  50: 0.2,
+  100: 0.3,
+  200: 0.45,
+  300: 0.7,
+  400: 0.95,
+  500: 1,
+  600: 0.95,
+  700: 0.85,
+  800: 0.65,
+  900: 0.45,
+  950: 0.3,
+};
+
+const MAX_PRIMARY_SCALE_CHROMA = 0.2;
+const MIN_PRIMARY_SCALE_CHROMA = 0.04;
+const NEUTRAL_CHROMA = 0.012;
+const DEFAULT_NEUTRAL_HUE_DEGREES = 260;
+
+function clampNumber(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(value, max));
+}
+
+function resolvePrimaryScaleChroma(seedChroma: number, step: ZoraColorScaleStep): number {
+  const cappedSeedChroma = clampNumber(seedChroma, 0, MAX_PRIMARY_SCALE_CHROMA);
+  const multiplier = PRIMARY_CHROMA_MULTIPLIER_BY_STEP[step];
+  const scaled = cappedSeedChroma * multiplier;
+
+  const bounded = clampNumber(scaled, 0, MAX_PRIMARY_SCALE_CHROMA);
+  const shouldEnforceMin = step >= 300 && step <= 700 && seedChroma >= MIN_PRIMARY_SCALE_CHROMA;
+
+  return shouldEnforceMin ? Math.max(bounded, MIN_PRIMARY_SCALE_CHROMA) : bounded;
+}
+
+function createScaleEntries(options: CreateZoraColorScaleOptions): ZoraColorScale {
+  const seed = parseHexToOklch(options.seed);
+
+  if (options.role === 'neutral') {
+    const hue = typeof seed.h === 'number' ? seed.h : DEFAULT_NEUTRAL_HUE_DEGREES;
+
+    return createScaleFromRamp({
+      hue,
+      chroma: NEUTRAL_CHROMA,
+      lightnessByStep: NEUTRAL_LIGHTNESS_BY_STEP,
+    });
+  }
+
+  return createScaleFromRamp({
+    hue: seed.h,
+    chromaByStep: (step) => resolvePrimaryScaleChroma(seed.c, step),
+    lightnessByStep: PRIMARY_LIGHTNESS_BY_STEP,
+  });
+}
+
+interface CreateScaleFromRampOptions {
+  hue: number;
+  chroma?: number;
+  chromaByStep?: (step: ZoraColorScaleStep) => number;
+  lightnessByStep: Record<ZoraColorScaleStep, number>;
+}
+
+function createScaleColor(
+  options: CreateScaleFromRampOptions,
+  step: ZoraColorScaleStep,
+): ZoraHexColor {
+  const lightness = options.lightnessByStep[step];
+  const chroma =
+    typeof options.chromaByStep === 'function' ? options.chromaByStep(step) : (options.chroma ?? 0);
+
+  const clamped = clampOklchToGamut({
+    l: clampNumber(lightness, 0, 1),
+    c: clampNumber(chroma, 0, 1),
+    h: options.hue,
+  });
+
+  return formatOklchAsHex(clamped);
+}
+
+function createScaleFromRamp(options: CreateScaleFromRampOptions): ZoraColorScale {
+  return {
+    50: createScaleColor(options, 50),
+    100: createScaleColor(options, 100),
+    200: createScaleColor(options, 200),
+    300: createScaleColor(options, 300),
+    400: createScaleColor(options, 400),
+    500: createScaleColor(options, 500),
+    600: createScaleColor(options, 600),
+    700: createScaleColor(options, 700),
+    800: createScaleColor(options, 800),
+    900: createScaleColor(options, 900),
+    950: createScaleColor(options, 950),
+  };
+}
+
+export function createZoraColorScale(options: CreateZoraColorScaleOptions): ZoraColorScale {
+  return createScaleEntries({
+    seed: options.seed,
+    role: options.role,
+  });
+}
+
+export function createZoraPrimaryScale(seed: ZoraHexColor): ZoraColorScale {
+  return createZoraColorScale({ seed, role: 'primary' });
+}
+
+export function createZoraNeutralScale(seed: ZoraHexColor = '#94a3b8'): ZoraColorScale {
+  return createZoraColorScale({ seed, role: 'neutral' });
+}

package/src/internal/color/types.ts

@@ -0,0 +1,15 @@
+import type { ZoraHexColor } from '../../theme/types';
+
+export interface ZoraOklchColor {
+  l: number;
+  c: number;
+  h: number;
+}
+
+export const ZORA_COLOR_SCALE_STEPS = [
+  50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950,
+] as const;
+
+export type ZoraColorScaleStep = (typeof ZORA_COLOR_SCALE_STEPS)[number];
+
+export type ZoraColorScale = Record<ZoraColorScaleStep, ZoraHexColor>;

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,