@ankhorage/zora 0.11.0 → 0.12.1

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

@@ -0,0 +1,145 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { ZoraHexColor } from '../../theme/types';
+import { normalizeHueDegrees } from './hue';
+import {
+  computeZoraHarmony,
+  parseHexToOklch,
+  type ZoraComputedHarmony,
+  type ZoraHarmonySlot,
+  type ZoraHarmonySlotId,
+} from './index';
+
+function hueDeltaDegrees(a: number, b: number): number {
+  const raw = Math.abs(a - b) % 360;
+  return Math.min(raw, 360 - raw);
+}
+
+function expectNormalizedHue(hue: number) {
+  expect(hue).toBeGreaterThanOrEqual(0);
+  expect(hue).toBeLessThan(360);
+}
+
+function getSlotIds(slots: readonly ZoraHarmonySlot[]): ZoraHarmonySlotId[] {
+  return slots.map((slot) => slot.id);
+}
+
+describe('computeZoraHarmony', () => {
+  test('monochromatic returns 1 slot', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'monochromatic');
+
+    expect(harmony.orderedSlots).toHaveLength(1);
+    expect(harmony.orderedSlots[0].id).toBe('base');
+  });
+
+  test('complementary returns 2 slots', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'complementary');
+
+    expect(harmony.orderedSlots).toHaveLength(2);
+    expect(harmony.orderedSlots[0].id).toBe('base');
+    expect(harmony.orderedSlots[1].id).toBe('a');
+  });
+
+  test('analogous returns 3 slots', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'analogous');
+
+    expect(harmony.orderedSlots).toHaveLength(3);
+    expect(getSlotIds(harmony.orderedSlots)).toEqual(['base', 'a', 'b']);
+  });
+
+  test('splitComplementary returns 3 slots', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'splitComplementary');
+
+    expect(harmony.orderedSlots).toHaveLength(3);
+    expect(getSlotIds(harmony.orderedSlots)).toEqual(['base', 'a', 'b']);
+  });
+
+  test('triadic returns 3 slots', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'triadic');
+
+    expect(harmony.orderedSlots).toHaveLength(3);
+    expect(getSlotIds(harmony.orderedSlots)).toEqual(['base', 'a', 'b']);
+  });
+
+  test('tetradic returns 4 slots', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'tetradic');
+
+    expect(harmony.orderedSlots).toHaveLength(4);
+    expect(getSlotIds(harmony.orderedSlots)).toEqual(['base', 'a', 'b', 'c']);
+  });
+
+  test('every computed hue is normalized to [0, 360)', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const harmonies = [
+      'monochromatic',
+      'complementary',
+      'analogous',
+      'splitComplementary',
+      'triadic',
+      'tetradic',
+    ] as const;
+
+    for (const kind of harmonies) {
+      const computed = computeZoraHarmony(seed, kind);
+      for (const slot of computed.orderedSlots) {
+        expectNormalizedHue(slot.hue);
+      }
+    }
+  });
+
+  test('base slot approximately matches parsed seed hue for a non-neutral seed', () => {
+    const seed: ZoraHexColor = '#ff00ff';
+    const seedOklch = parseHexToOklch(seed);
+
+    const computed = computeZoraHarmony(seed, 'complementary');
+    const [base] = computed.orderedSlots;
+
+    expect(base).toBeDefined();
+    if (!base) {
+      throw new Error('Expected a base harmony slot.');
+    }
+
+    expect(base.id).toBe('base');
+    expect(hueDeltaDegrees(seedOklch.h, base.hue)).toBeLessThan(0.5);
+  });
+
+  test('neutral/low-chroma seed uses a stable fallback hue', () => {
+    const seed: ZoraHexColor = '#808080';
+    const computed = computeZoraHarmony(seed, 'monochromatic');
+
+    expect(computed.orderedSlots).toHaveLength(1);
+    expect(computed.orderedSlots[0].hue).toBe(260);
+  });
+
+  test('is deterministic for the same seed/harmony', () => {
+    const seed: ZoraHexColor = '#0f766e';
+
+    expect(computeZoraHarmony(seed, 'triadic')).toEqual(computeZoraHarmony(seed, 'triadic'));
+  });
+
+  test('complementary slots are based on base hue + 180', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const computed = computeZoraHarmony(seed, 'complementary');
+    const [base, a] = computed.orderedSlots;
+
+    expect(base).toBeDefined();
+    expect(a).toBeDefined();
+    if (!base || !a) {
+      throw new Error('Expected complementary harmony slots.');
+    }
+
+    expect(hueDeltaDegrees(a.hue, normalizeHueDegrees(base.hue + 180))).toBeLessThan(0.0001);
+  });
+
+  test('throws on invalid seed in test/development', () => {
+    const invalid: ZoraHexColor = '#nope';
+
+    expect(() => computeZoraHarmony(invalid, 'triadic')).toThrow();
+  });
+});

package/src/internal/color/harmony.ts

@@ -0,0 +1,96 @@
+import type { ZoraColorHarmony, ZoraHexColor } from '../../theme/types';
+import { normalizeHueDegrees, rotateHueDegrees } from './hue';
+import { parseHexToOklch } from './oklch';
+
+export type ZoraHarmonySlotId = 'base' | 'a' | 'b' | 'c';
+
+export interface ZoraHarmonySlot {
+  id: ZoraHarmonySlotId;
+  hue: number;
+}
+
+export interface ZoraComputedHarmony {
+  kind: ZoraColorHarmony;
+  orderedSlots: readonly ZoraHarmonySlot[];
+}
+
+const DEFAULT_HARMONY_HUE_DEGREES = 260;
+const MIN_SEED_CHROMA_FOR_HARMONY_HUE = 0.03;
+
+function createSlot(id: ZoraHarmonySlotId, hue: number): ZoraHarmonySlot {
+  return { id, hue: normalizeHueDegrees(hue) };
+}
+
+function resolveSeedHueDegrees(seed: ZoraHexColor): number {
+  const parsed = parseHexToOklch(seed);
+
+  if (!Number.isFinite(parsed.h) || parsed.c < MIN_SEED_CHROMA_FOR_HARMONY_HUE) {
+    return DEFAULT_HARMONY_HUE_DEGREES;
+  }
+
+  return normalizeHueDegrees(parsed.h);
+}
+
+export function computeZoraHarmony(
+  seed: ZoraHexColor,
+  harmony: ZoraColorHarmony,
+): ZoraComputedHarmony {
+  const baseHue = resolveSeedHueDegrees(seed);
+
+  if (harmony === 'monochromatic') {
+    return {
+      kind: harmony,
+      orderedSlots: [createSlot('base', baseHue)],
+    };
+  }
+
+  if (harmony === 'complementary') {
+    return {
+      kind: harmony,
+      orderedSlots: [createSlot('base', baseHue), createSlot('a', rotateHueDegrees(baseHue, 180))],
+    };
+  }
+
+  if (harmony === 'analogous') {
+    return {
+      kind: harmony,
+      orderedSlots: [
+        createSlot('base', baseHue),
+        createSlot('a', rotateHueDegrees(baseHue, -30)),
+        createSlot('b', rotateHueDegrees(baseHue, 30)),
+      ],
+    };
+  }
+
+  if (harmony === 'splitComplementary') {
+    return {
+      kind: harmony,
+      orderedSlots: [
+        createSlot('base', baseHue),
+        createSlot('a', rotateHueDegrees(baseHue, 150)),
+        createSlot('b', rotateHueDegrees(baseHue, 210)),
+      ],
+    };
+  }
+
+  if (harmony === 'triadic') {
+    return {
+      kind: harmony,
+      orderedSlots: [
+        createSlot('base', baseHue),
+        createSlot('a', rotateHueDegrees(baseHue, 120)),
+        createSlot('b', rotateHueDegrees(baseHue, 240)),
+      ],
+    };
+  }
+
+  return {
+    kind: harmony,
+    orderedSlots: [
+      createSlot('base', baseHue),
+      createSlot('a', rotateHueDegrees(baseHue, 90)),
+      createSlot('b', rotateHueDegrees(baseHue, 180)),
+      createSlot('c', rotateHueDegrees(baseHue, 270)),
+    ],
+  };
+}

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

@@ -0,0 +1,28 @@
+import { describe, expect, test } from 'bun:test';
+
+import { normalizeHueDegrees, rotateHueDegrees } from './hue';
+
+describe('normalizeHueDegrees', () => {
+  test('normalizes negative hues into [0, 360)', () => {
+    expect(normalizeHueDegrees(-30)).toBe(330);
+    expect(normalizeHueDegrees(-390)).toBe(330);
+  });
+
+  test('normalizes hues >= 360 into [0, 360)', () => {
+    expect(normalizeHueDegrees(390)).toBe(30);
+    expect(normalizeHueDegrees(720)).toBe(0);
+  });
+
+  test('preserves in-range hues', () => {
+    expect(normalizeHueDegrees(0)).toBe(0);
+    expect(normalizeHueDegrees(12.5)).toBe(12.5);
+    expect(normalizeHueDegrees(359.99)).toBe(359.99);
+  });
+});
+
+describe('rotateHueDegrees', () => {
+  test('rotates and normalizes', () => {
+    expect(rotateHueDegrees(350, 30)).toBe(20);
+    expect(rotateHueDegrees(10, -30)).toBe(340);
+  });
+});

package/src/internal/color/hue.ts

@@ -0,0 +1,7 @@
+export function normalizeHueDegrees(hue: number): number {
+  return ((hue % 360) + 360) % 360;
+}
+
+export function rotateHueDegrees(hue: number, delta: number): number {
+  return normalizeHueDegrees(hue + delta);
+}

package/src/internal/color/index.ts

@@ -0,0 +1,15 @@
+export {
+  computeZoraHarmony,
+  type ZoraComputedHarmony,
+  type ZoraHarmonySlot,
+  type ZoraHarmonySlotId,
+} from './harmony';
+export { parseHexToOklch } from './oklch';
+export { resolveModePrimaryColor } from './primary';
+export {
+  createZoraColorScale,
+  type CreateZoraColorScaleOptions,
+  createZoraNeutralScale,
+  createZoraPrimaryScale,
+} from './scales';
+export { ZORA_COLOR_SCALE_STEPS, type ZoraColorScale, type ZoraColorScaleStep } from './types';

package/src/internal/color/oklch.ts

@@ -0,0 +1,65 @@
+import { converter, formatHex, parse, toGamut } from 'culori';
+
+import type { ZoraHexColor } from '../../theme/types';
+import { normalizeHueDegrees } from './hue';
+import type { ZoraOklchColor } from './types';
+
+const toOklch = converter('oklch');
+const gamutMapToSrgb = toGamut('rgb', 'oklch');
+
+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/scales.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { ZoraHexColor } from '../../theme/types';
+import {
+  createZoraColorScale,
+  type CreateZoraColorScaleOptions,
+  createZoraNeutralScale,
+  createZoraPrimaryScale,
+  parseHexToOklch,
+  ZORA_COLOR_SCALE_STEPS,
+  type ZoraColorScale,
+  type ZoraColorScaleStep,
+} from './index';
+
+function isSixDigitLowercaseHexColor(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);
+}
+
+function getStepValues(scale: ZoraColorScale): { step: ZoraColorScaleStep; hex: ZoraHexColor }[] {
+  return ZORA_COLOR_SCALE_STEPS.map((step) => ({ step, hex: scale[step] }));
+}
+
+function assertScaleKeys(scale: ZoraColorScale) {
+  const keys = Object.keys(scale)
+    .map((key) => Number(key))
+    .sort((a, b) => a - b);
+
+  expect(keys).toEqual([...ZORA_COLOR_SCALE_STEPS]);
+}
+
+function assertDecreasingLightness(scale: ZoraColorScale) {
+  const lightness = getStepValues(scale).map(({ hex }) => parseHexToOklch(hex).l);
+
+  for (let index = 0; index < lightness.length - 1; index += 1) {
+    expect(lightness[index]).toBeGreaterThan(lightness[index + 1]);
+  }
+}
+
+describe('createZoraPrimaryScale', () => {
+  test('matches createZoraColorScale({ role: primary })', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const options: CreateZoraColorScaleOptions = { seed, role: 'primary' };
+
+    expect(createZoraPrimaryScale(seed)).toEqual(createZoraColorScale(options));
+  });
+
+  test('returns all 50–950 keys and valid lowercase 6-digit hex values', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const scale = createZoraPrimaryScale(seed);
+
+    assertScaleKeys(scale);
+
+    for (const { hex } of getStepValues(scale)) {
+      expect(isSixDigitLowercaseHexColor(hex)).toBe(true);
+    }
+  });
+
+  test('is deterministic for the same seed', () => {
+    const seed: ZoraHexColor = '#0f766e';
+
+    expect(createZoraPrimaryScale(seed)).toEqual(createZoraPrimaryScale(seed));
+  });
+
+  test('lightness decreases from 50 to 950', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const scale = createZoraPrimaryScale(seed);
+
+    assertDecreasingLightness(scale);
+  });
+
+  test('preserves hue approximately for mid steps', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const seedOklch = parseHexToOklch(seed);
+    const scale = createZoraPrimaryScale(seed);
+
+    const midSteps: ZoraColorScaleStep[] = [400, 500, 600, 700];
+    for (const step of midSteps) {
+      const oklch = parseHexToOklch(scale[step]);
+      expect(hueDeltaDegrees(seedOklch.h, oklch.h)).toBeLessThan(20);
+    }
+  });
+
+  test('mid steps have higher chroma than extremes for a saturated seed', () => {
+    const seed: ZoraHexColor = '#ff00ff';
+    const scale = createZoraPrimaryScale(seed);
+
+    const chroma50 = parseHexToOklch(scale[50]).c;
+    const chroma950 = parseHexToOklch(scale[950]).c;
+    const chroma500 = parseHexToOklch(scale[500]).c;
+    const chroma600 = parseHexToOklch(scale[600]).c;
+
+    const extremes = Math.max(chroma50, chroma950);
+    const mid = Math.max(chroma500, chroma600);
+
+    expect(mid).toBeGreaterThan(extremes);
+  });
+
+  test('bounds saturated inputs to stay in gamut', () => {
+    const seed: ZoraHexColor = '#ff00ff';
+    const scale = createZoraPrimaryScale(seed);
+
+    for (const { hex } of getStepValues(scale)) {
+      expect(isSixDigitLowercaseHexColor(hex)).toBe(true);
+      expect(() => parseHexToOklch(hex)).not.toThrow();
+    }
+  });
+
+  test('throws on invalid seed in test/development', () => {
+    const invalid: ZoraHexColor = '#nope';
+
+    expect(() => createZoraPrimaryScale(invalid)).toThrow();
+  });
+});
+
+describe('createZoraNeutralScale', () => {
+  test('works with and without a seed', () => {
+    const seeded = createZoraNeutralScale('#0f766e');
+    const unseeded = createZoraNeutralScale();
+
+    assertScaleKeys(seeded);
+    assertScaleKeys(unseeded);
+  });
+
+  test('returns low-chroma neutrals', () => {
+    const scale = createZoraNeutralScale('#0f766e');
+
+    for (const { hex } of getStepValues(scale)) {
+      const oklch = parseHexToOklch(hex);
+      expect(oklch.c).toBeLessThanOrEqual(0.03);
+    }
+  });
+
+  test('lightness decreases from 50 to 950', () => {
+    const scale = createZoraNeutralScale('#0f766e');
+
+    assertDecreasingLightness(scale);
+  });
+
+  test('avoids pure black/white in the generated steps', () => {
+    const scale = createZoraNeutralScale('#0f766e');
+    const values = getStepValues(scale).map(({ hex }) => hex);
+
+    expect(values).not.toContain('#000000');
+    expect(values).not.toContain('#ffffff');
+  });
+});