@ankhorage/zora 0.12.2 → 0.13.1

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

@@ -0,0 +1,89 @@
+import { describe, expect, test } from 'bun:test';
+
+import { ZORA_COLOR_TONES } from '../../theme/types';
+import {
+  getZoraColorToneRecipe,
+  getZoraColorToneRoleChromaFactor,
+  type ZoraColorToneRecipe,
+  type ZoraHueScaleRoleId,
+} from './index';
+
+const HUE_BACKED_ROLES: readonly ZoraHueScaleRoleId[] = [
+  'primary',
+  'secondary',
+  'accent',
+  'highlight',
+  'surfaceTint',
+];
+
+function expectFinitePositive(value: number) {
+  expect(Number.isFinite(value)).toBe(true);
+  expect(value).toBeGreaterThan(0);
+}
+
+function expectSaneRecipe(recipe: ZoraColorToneRecipe) {
+  expectFinitePositive(recipe.maxChroma);
+  expectFinitePositive(recipe.minMidChroma);
+  expect(recipe.minMidChroma).toBeLessThan(recipe.maxChroma);
+
+  for (const role of HUE_BACKED_ROLES) {
+    expectFinitePositive(getZoraColorToneRoleChromaFactor(recipe, role));
+  }
+}
+
+describe('color tone recipes', () => {
+  test('every ZORA color tone has a recipe', () => {
+    for (const colorTone of ZORA_COLOR_TONES) {
+      expect(getZoraColorToneRecipe(colorTone).colorTone).toBe(colorTone);
+    }
+  });
+
+  test('every recipe has sane chroma values and all hue-backed role factors', () => {
+    for (const colorTone of ZORA_COLOR_TONES) {
+      expectSaneRecipe(getZoraColorToneRecipe(colorTone));
+    }
+  });
+
+  test('records the initial background and foreground lane pairings', () => {
+    expect(getZoraColorToneRecipe('fluorescent').laneRecipe).toEqual({
+      backgroundTone: 'obsidian',
+      foregroundTone: 'fluorescent',
+    });
+    expect(getZoraColorToneRecipe('obsidian').laneRecipe).toEqual({
+      backgroundTone: 'obsidian',
+      foregroundTone: 'fluorescent',
+    });
+    expect(getZoraColorToneRecipe('pastel').laneRecipe).toEqual({
+      backgroundTone: 'pastel',
+      foregroundTone: 'jewel',
+    });
+    expect(getZoraColorToneRecipe('earth').laneRecipe).toEqual({
+      backgroundTone: 'earth',
+      foregroundTone: 'mineral',
+    });
+  });
+
+  test('surface tint remains lower intensity than foreground action roles', () => {
+    for (const colorTone of ZORA_COLOR_TONES) {
+      const recipe = getZoraColorToneRecipe(colorTone);
+      const surfaceTint = getZoraColorToneRoleChromaFactor(recipe, 'surfaceTint');
+
+      expect(surfaceTint).toBeLessThan(getZoraColorToneRoleChromaFactor(recipe, 'primary'));
+      expect(surfaceTint).toBeLessThan(getZoraColorToneRoleChromaFactor(recipe, 'accent'));
+      expect(surfaceTint).toBeLessThan(getZoraColorToneRoleChromaFactor(recipe, 'highlight'));
+    }
+  });
+
+  test('high-energy tones allow higher chroma than neutral and pastel', () => {
+    expect(getZoraColorToneRecipe('fluorescent').maxChroma).toBeGreaterThan(
+      getZoraColorToneRecipe('neutral').maxChroma,
+    );
+    expect(getZoraColorToneRecipe('fluorescent').maxChroma).toBeGreaterThan(
+      getZoraColorToneRecipe('pastel').maxChroma,
+    );
+  });
+
+  test('getter is deterministic', () => {
+    expect(getZoraColorToneRecipe('jewel')).toEqual(getZoraColorToneRecipe('jewel'));
+  });
+});

package/src/internal/color/colorToneRecipes.ts

@@ -0,0 +1,167 @@
+import type { ZoraColorTone } from '../../theme/types';
+import type { ZoraHueScaleRoleId } from './scales';
+
+export interface ZoraColorToneLaneRecipe {
+  backgroundTone: ZoraColorTone;
+  foregroundTone: ZoraColorTone;
+}
+
+export interface ZoraColorToneRoleChromaFactors {
+  primary: number;
+  secondary: number;
+  accent: number;
+  highlight: number;
+  surfaceTint: number;
+}
+
+export interface ZoraColorToneRecipe {
+  colorTone: ZoraColorTone;
+  laneRecipe: ZoraColorToneLaneRecipe;
+  roleChromaFactors: ZoraColorToneRoleChromaFactors;
+  maxChroma: number;
+  minMidChroma: number;
+}
+
+const ZORA_COLOR_TONE_RECIPES = {
+  neutral: {
+    colorTone: 'neutral',
+    laneRecipe: { backgroundTone: 'neutral', foregroundTone: 'jewel' },
+    roleChromaFactors: {
+      primary: 0.72,
+      secondary: 0.48,
+      accent: 0.56,
+      highlight: 0.6,
+      surfaceTint: 0.12,
+    },
+    maxChroma: 0.14,
+    minMidChroma: 0.025,
+  },
+  pastel: {
+    colorTone: 'pastel',
+    laneRecipe: { backgroundTone: 'pastel', foregroundTone: 'jewel' },
+    roleChromaFactors: {
+      primary: 0.58,
+      secondary: 0.48,
+      accent: 0.55,
+      highlight: 0.62,
+      surfaceTint: 0.2,
+    },
+    maxChroma: 0.12,
+    minMidChroma: 0.02,
+  },
+  earth: {
+    colorTone: 'earth',
+    laneRecipe: { backgroundTone: 'earth', foregroundTone: 'mineral' },
+    roleChromaFactors: {
+      primary: 0.64,
+      secondary: 0.52,
+      accent: 0.58,
+      highlight: 0.6,
+      surfaceTint: 0.16,
+    },
+    maxChroma: 0.13,
+    minMidChroma: 0.022,
+  },
+  mineral: {
+    colorTone: 'mineral',
+    laneRecipe: { backgroundTone: 'mineral', foregroundTone: 'jewel' },
+    roleChromaFactors: {
+      primary: 0.7,
+      secondary: 0.56,
+      accent: 0.64,
+      highlight: 0.68,
+      surfaceTint: 0.16,
+    },
+    maxChroma: 0.14,
+    minMidChroma: 0.025,
+  },
+  muted: {
+    colorTone: 'muted',
+    laneRecipe: { backgroundTone: 'muted', foregroundTone: 'jewel' },
+    roleChromaFactors: {
+      primary: 0.6,
+      secondary: 0.5,
+      accent: 0.56,
+      highlight: 0.6,
+      surfaceTint: 0.14,
+    },
+    maxChroma: 0.12,
+    minMidChroma: 0.02,
+  },
+  jewel: {
+    colorTone: 'jewel',
+    laneRecipe: { backgroundTone: 'neutral', foregroundTone: 'jewel' },
+    roleChromaFactors: {
+      primary: 1,
+      secondary: 0.72,
+      accent: 0.85,
+      highlight: 1,
+      surfaceTint: 0.18,
+    },
+    maxChroma: 0.2,
+    minMidChroma: 0.04,
+  },
+  fluorescent: {
+    colorTone: 'fluorescent',
+    laneRecipe: { backgroundTone: 'obsidian', foregroundTone: 'fluorescent' },
+    roleChromaFactors: {
+      primary: 1.12,
+      secondary: 0.82,
+      accent: 1.05,
+      highlight: 1.18,
+      surfaceTint: 0.22,
+    },
+    maxChroma: 0.24,
+    minMidChroma: 0.045,
+  },
+  obsidian: {
+    colorTone: 'obsidian',
+    laneRecipe: { backgroundTone: 'obsidian', foregroundTone: 'fluorescent' },
+    roleChromaFactors: {
+      primary: 1.08,
+      secondary: 0.78,
+      accent: 1,
+      highlight: 1.12,
+      surfaceTint: 0.2,
+    },
+    maxChroma: 0.22,
+    minMidChroma: 0.04,
+  },
+  vaporwave: {
+    colorTone: 'vaporwave',
+    laneRecipe: { backgroundTone: 'pastel', foregroundTone: 'fluorescent' },
+    roleChromaFactors: {
+      primary: 0.95,
+      secondary: 0.72,
+      accent: 1,
+      highlight: 1.08,
+      surfaceTint: 0.24,
+    },
+    maxChroma: 0.2,
+    minMidChroma: 0.035,
+  },
+  monochromeAccent: {
+    colorTone: 'monochromeAccent',
+    laneRecipe: { backgroundTone: 'neutral', foregroundTone: 'jewel' },
+    roleChromaFactors: {
+      primary: 0.88,
+      secondary: 0.36,
+      accent: 0.95,
+      highlight: 0.88,
+      surfaceTint: 0.08,
+    },
+    maxChroma: 0.18,
+    minMidChroma: 0.035,
+  },
+} satisfies Record<ZoraColorTone, ZoraColorToneRecipe>;
+
+export function getZoraColorToneRecipe(colorTone: ZoraColorTone): ZoraColorToneRecipe {
+  return ZORA_COLOR_TONE_RECIPES[colorTone];
+}
+
+export function getZoraColorToneRoleChromaFactor(
+  recipe: ZoraColorToneRecipe,
+  role: ZoraHueScaleRoleId,
+): number {
+  return recipe.roleChromaFactors[role];
+}

package/src/internal/color/index.ts

@@ -1,3 +1,10 @@
+export {
+  getZoraColorToneRecipe,
+  getZoraColorToneRoleChromaFactor,
+  type ZoraColorToneLaneRecipe,
+  type ZoraColorToneRecipe,
+  type ZoraColorToneRoleChromaFactors,
+} from './colorToneRecipes';
 export {
   computeZoraHarmony,
   type ZoraComputedHarmony,
@@ -13,10 +20,20 @@ export {
   type ZoraHueRoleAssignment,
   type ZoraHueRoleId,
 } from './roleHues';
+export {
+  createZoraRoleColorScales,
+  getZoraRoleColorScale,
+  ZORA_COLOR_SCALE_ROLE_ORDER,
+  type ZoraColorScaleRoleId,
+  type ZoraComputedRoleColorScales,
+  type ZoraRoleColorScale,
+} from './roleScales';
 export {
   createZoraColorScale,
   type CreateZoraColorScaleOptions,
+  type CreateZoraHueScaleOptions,
   createZoraNeutralScale,
   createZoraPrimaryScale,
+  type ZoraHueScaleRoleId,
 } from './scales';
 export { ZORA_COLOR_SCALE_STEPS, type ZoraColorScale, type ZoraColorScaleStep } from './types';

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

@@ -25,7 +25,7 @@ const ROLE_ORDER: readonly ZoraHueRoleId[] = [
 
 function expectEveryRoleOnce(roles: ReturnType<typeof assignZoraHarmonyRoleHues>) {
   expect(roles.assignments).toHaveLength(ROLE_ORDER.length);
-  expect(roles.assignments.map((assignment) => assignment.role)).toEqual(ROLE_ORDER);
+  expect(roles.assignments.map((assignment) => assignment.role)).toEqual([...ROLE_ORDER]);
 }
 
 describe('assignZoraHarmonyRoleHues', () => {

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

@@ -0,0 +1,220 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { ZoraColorTone, ZoraHexColor } from '../../theme/types';
+import {
+  assignZoraHarmonyRoleHues,
+  computeZoraHarmony,
+  createZoraRoleColorScales,
+  getZoraRoleColorScale,
+  parseHexToOklch,
+  ZORA_COLOR_SCALE_ROLE_ORDER,
+  ZORA_COLOR_SCALE_STEPS,
+  type ZoraColorScale,
+  type ZoraColorScaleStep,
+  type ZoraComputedHueRoles,
+  type ZoraRoleColorScale,
+} 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 assertNoPureBlackOrWhite(scale: ZoraColorScale) {
+  const values = getStepValues(scale).map(({ hex }) => hex);
+  expect(values).not.toContain('#000000');
+  expect(values).not.toContain('#ffffff');
+}
+
+function buildHueRoles(assignments: ZoraComputedHueRoles['assignments']): ZoraComputedHueRoles {
+  return {
+    harmony: 'tetradic',
+    assignments,
+  };
+}
+
+function createCompleteHueRoles(): ZoraComputedHueRoles {
+  return buildHueRoles([
+    { role: 'primary', hue: 120, sourceSlotId: 'base' },
+    { role: 'secondary', hue: 200, sourceSlotId: 'a' },
+    { role: 'accent', hue: 280, sourceSlotId: 'b' },
+    { role: 'highlight', hue: 20, sourceSlotId: 'c' },
+    { role: 'surfaceTint', hue: 160, sourceSlotId: 'a' },
+  ]);
+}
+
+function createScales(colorTone: ZoraColorTone = 'jewel') {
+  return createZoraRoleColorScales({
+    colorTone,
+    hueRoles: createCompleteHueRoles(),
+    seed: '#0f766e',
+  });
+}
+
+function requireHueBackedSourceHue(role: ZoraRoleColorScale): number {
+  if (typeof role.sourceHue !== 'number') {
+    throw new Error(`[zora] Expected "${role.role}" role scale to include a sourceHue.`);
+  }
+  return role.sourceHue;
+}
+
+describe('createZoraRoleColorScales', () => {
+  test('returns all roles exactly once in deterministic order', () => {
+    const scales = createScales();
+
+    expect(scales.roles).toHaveLength(ZORA_COLOR_SCALE_ROLE_ORDER.length);
+    expect(scales.roles.map((entry) => entry.role)).toEqual([...ZORA_COLOR_SCALE_ROLE_ORDER]);
+    expect(new Set(scales.roles.map((entry) => entry.role)).size).toBe(
+      ZORA_COLOR_SCALE_ROLE_ORDER.length,
+    );
+  });
+
+  test('every scale contains exactly all 50–950 keys and valid lowercase 6-digit hex values', () => {
+    const scales = createScales();
+
+    for (const role of scales.roles) {
+      assertScaleKeys(role.scale);
+      for (const { hex } of getStepValues(role.scale)) {
+        expect(isSixDigitLowercaseHexColor(hex)).toBe(true);
+      }
+    }
+  });
+
+  test('output is deterministic for the same input', () => {
+    expect(createScales()).toEqual(createScales());
+  });
+
+  test('role hue is preserved approximately for mid steps', () => {
+    const scales = createZoraRoleColorScales({
+      colorTone: 'jewel',
+      hueRoles: buildHueRoles([
+        { role: 'primary', hue: 115, sourceSlotId: 'base' },
+        { role: 'secondary', hue: 210, sourceSlotId: 'a' },
+        { role: 'accent', hue: 300, sourceSlotId: 'b' },
+        { role: 'highlight', hue: 25, sourceSlotId: 'c' },
+        { role: 'surfaceTint', hue: 165, sourceSlotId: 'a' },
+      ]),
+      seed: '#0f766e',
+    });
+
+    const midSteps: ZoraColorScaleStep[] = [400, 500, 600, 700];
+    for (const roleId of ['primary', 'secondary', 'accent', 'highlight', 'surfaceTint'] as const) {
+      const role = getZoraRoleColorScale(scales, roleId);
+      const expectedHue = requireHueBackedSourceHue(role);
+
+      for (const step of midSteps) {
+        const oklch = parseHexToOklch(role.scale[step]);
+        expect(hueDeltaDegrees(expectedHue, oklch.h)).toBeLessThan(25);
+      }
+    }
+  });
+
+  test('surfaceTint scale has lower chroma than primary/accent/highlight for mid steps', () => {
+    const scales = createScales('jewel');
+    const surfaceTint = getZoraRoleColorScale(scales, 'surfaceTint').scale;
+    const primary = getZoraRoleColorScale(scales, 'primary').scale;
+    const accent = getZoraRoleColorScale(scales, 'accent').scale;
+    const highlight = getZoraRoleColorScale(scales, 'highlight').scale;
+    const step: ZoraColorScaleStep = 500;
+    const surfaceTintChroma = parseHexToOklch(surfaceTint[step]).c;
+
+    expect(surfaceTintChroma).toBeLessThan(parseHexToOklch(primary[step]).c);
+    expect(surfaceTintChroma).toBeLessThan(parseHexToOklch(accent[step]).c);
+    expect(surfaceTintChroma).toBeLessThan(parseHexToOklch(highlight[step]).c);
+  });
+
+  test('colorTone changes role chroma behavior internally', () => {
+    const neutral = createScales('neutral');
+    const fluorescent = createScales('fluorescent');
+    const step: ZoraColorScaleStep = 500;
+
+    const neutralPrimary = parseHexToOklch(getZoraRoleColorScale(neutral, 'primary').scale[step]).c;
+    const fluorescentPrimary = parseHexToOklch(
+      getZoraRoleColorScale(fluorescent, 'primary').scale[step],
+    ).c;
+
+    expect(fluorescentPrimary).toBeGreaterThan(neutralPrimary);
+  });
+
+  test('pastel keeps surfaceTint lower chroma than fluorescent foreground roles', () => {
+    const pastel = createScales('pastel');
+    const fluorescent = createScales('fluorescent');
+    const step: ZoraColorScaleStep = 500;
+
+    const pastelSurfaceTint = parseHexToOklch(
+      getZoraRoleColorScale(pastel, 'surfaceTint').scale[step],
+    ).c;
+    const fluorescentAccent = parseHexToOklch(
+      getZoraRoleColorScale(fluorescent, 'accent').scale[step],
+    ).c;
+
+    expect(pastelSurfaceTint).toBeLessThan(fluorescentAccent);
+  });
+
+  test('neutral scale has low chroma', () => {
+    const neutral = getZoraRoleColorScale(createScales(), 'neutral').scale;
+
+    for (const { hex } of getStepValues(neutral)) {
+      expect(parseHexToOklch(hex).c).toBeLessThanOrEqual(0.03);
+    }
+  });
+
+  test('missing required hue role throws a clear error', () => {
+    const hueRoles = buildHueRoles([
+      { role: 'primary', hue: 120, sourceSlotId: 'base' },
+      { role: 'secondary', hue: 200, sourceSlotId: 'a' },
+      { role: 'accent', hue: 280, sourceSlotId: 'b' },
+      { role: 'surfaceTint', hue: 160, sourceSlotId: 'a' },
+    ]);
+
+    expect(() =>
+      createZoraRoleColorScales({ colorTone: 'jewel', hueRoles, seed: '#0f766e' }),
+    ).toThrow('highlight');
+  });
+
+  test('no role scale contains pure black/white by default', () => {
+    const scales = createScales();
+
+    for (const role of scales.roles) {
+      assertNoPureBlackOrWhite(role.scale);
+    }
+  });
+
+  test('does not mutate input hueRoles', () => {
+    const hueRoles = createCompleteHueRoles();
+    const snapshot = JSON.stringify(hueRoles);
+
+    createZoraRoleColorScales({ colorTone: 'jewel', hueRoles, seed: '#0f766e' });
+
+    expect(JSON.stringify(hueRoles)).toBe(snapshot);
+  });
+
+  test('integration: harmony -> role hues -> role scales pipeline connects', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const harmony = computeZoraHarmony(seed, 'tetradic');
+    const hueRoles = assignZoraHarmonyRoleHues(harmony);
+
+    const scales = createZoraRoleColorScales({ colorTone: 'jewel', hueRoles, seed });
+
+    expect(scales.roles.map((entry) => entry.role)).toEqual([...ZORA_COLOR_SCALE_ROLE_ORDER]);
+    for (const role of scales.roles) {
+      assertScaleKeys(role.scale);
+    }
+  });
+});

package/src/internal/color/roleScales.ts

@@ -0,0 +1,127 @@
+import type { ZoraColorTone, ZoraHexColor } from '../../theme/types';
+import { getZoraColorToneRecipe } from './colorToneRecipes';
+import { parseHexToOklch } from './oklch';
+import {
+  getZoraHueRoleAssignment,
+  type ZoraComputedHueRoles,
+  type ZoraHueRoleId,
+} from './roleHues';
+import {
+  createZoraHueScale,
+  type CreateZoraHueScaleOptions,
+  createZoraNeutralScale,
+  type ZoraHueScaleRoleId,
+} from './scales';
+import type { ZoraColorScale } from './types';
+
+export type ZoraColorScaleRoleId =
+  | 'primary'
+  | 'secondary'
+  | 'accent'
+  | 'highlight'
+  | 'surfaceTint'
+  | 'neutral';
+
+export const ZORA_COLOR_SCALE_ROLE_ORDER: readonly ZoraColorScaleRoleId[] = [
+  'primary',
+  'secondary',
+  'accent',
+  'highlight',
+  'surfaceTint',
+  'neutral',
+];
+
+export interface ZoraRoleColorScale {
+  role: ZoraColorScaleRoleId;
+  sourceHue?: number;
+  scale: ZoraColorScale;
+}
+
+export interface ZoraComputedRoleColorScales {
+  roles: readonly ZoraRoleColorScale[];
+}
+
+export function getZoraRoleColorScale(
+  scales: ZoraComputedRoleColorScales,
+  role: ZoraColorScaleRoleId,
+): ZoraRoleColorScale {
+  const found = scales.roles.find((entry) => entry.role === role);
+  if (!found) {
+    throw new Error(`[zora] Expected role color scales to include "${role}".`);
+  }
+  return found;
+}
+
+function resolveSeedChroma(seed: ZoraHexColor): number {
+  return parseHexToOklch(seed).c;
+}
+
+function createHueBackedRoleScale(options: {
+  colorTone: ZoraColorTone;
+  hueRoles: ZoraComputedHueRoles;
+  seedChroma: number;
+  role: ZoraHueRoleId;
+}): ZoraRoleColorScale {
+  const assignment = getZoraHueRoleAssignment(options.hueRoles, options.role);
+  const colorToneRecipe = getZoraColorToneRecipe(options.colorTone);
+  const hueScaleRole: ZoraHueScaleRoleId = options.role;
+  const hueScaleOptions: CreateZoraHueScaleOptions = {
+    hue: assignment.hue,
+    seedChroma: options.seedChroma,
+    role: hueScaleRole,
+    colorToneRecipe,
+  };
+
+  return {
+    role: options.role,
+    sourceHue: assignment.hue,
+    scale: createZoraHueScale(hueScaleOptions),
+  };
+}
+
+export function createZoraRoleColorScales(options: {
+  hueRoles: ZoraComputedHueRoles;
+  seed: ZoraHexColor;
+  colorTone: ZoraColorTone;
+}): ZoraComputedRoleColorScales {
+  const seedChroma = resolveSeedChroma(options.seed);
+
+  const roles: ZoraRoleColorScale[] = [
+    createHueBackedRoleScale({
+      colorTone: options.colorTone,
+      hueRoles: options.hueRoles,
+      seedChroma,
+      role: 'primary',
+    }),
+    createHueBackedRoleScale({
+      colorTone: options.colorTone,
+      hueRoles: options.hueRoles,
+      seedChroma,
+      role: 'secondary',
+    }),
+    createHueBackedRoleScale({
+      colorTone: options.colorTone,
+      hueRoles: options.hueRoles,
+      seedChroma,
+      role: 'accent',
+    }),
+    createHueBackedRoleScale({
+      colorTone: options.colorTone,
+      hueRoles: options.hueRoles,
+      seedChroma,
+      role: 'highlight',
+    }),
+    createHueBackedRoleScale({
+      colorTone: options.colorTone,
+      hueRoles: options.hueRoles,
+      seedChroma,
+      role: 'surfaceTint',
+    }),
+    {
+      role: 'neutral',
+      scale: createZoraNeutralScale(options.seed),
+    },
+  ];
+
+  return { roles };
+}