@ankhorage/color-theory 0.0.1

package/src/neutral.ts

@@ -0,0 +1,68 @@
+import type { ColorHarmony, GeneratedHarmonyRoleColors } from './harmony';
+import type { HexColor } from './hex';
+import { normalizeHueDegrees, oklchToHex, parseHexToOklch } from './internal-culori';
+import { type ColorSwatch, type ColorSwatchDiagnostics, generateColorSwatch } from './swatches';
+
+export const MIN_HUEFUL_CHROMA = 0.015;
+
+export interface NeutralSwatchResult {
+  neutralKeyColor: HexColor;
+  neutral: ColorSwatch;
+  diagnostics: ColorSwatchDiagnostics;
+}
+
+export interface GeneratedNeutralMetadata {
+  neutralKeyColor: HexColor;
+  diagnostics: ColorSwatchDiagnostics;
+}
+
+function pickTintSourceHex(
+  roleColors: GeneratedHarmonyRoleColors,
+  harmony: ColorHarmony,
+): HexColor {
+  const byMapping: Partial<Record<ColorHarmony, HexColor | undefined>> = {
+    monochromatic: roleColors.primary.hex,
+    complementary: roleColors.secondary?.hex,
+    analogous: roleColors.tertiary?.hex,
+    splitComplementary: roleColors.tertiary?.hex,
+    triadic: roleColors.tertiary?.hex,
+    tetradic: roleColors.tertiary?.hex,
+  };
+
+  return (
+    byMapping[harmony] ??
+    roleColors.tertiary?.hex ??
+    roleColors.secondary?.hex ??
+    roleColors.primary.hex
+  );
+}
+
+function clampNumber(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min;
+  return Math.min(max, Math.max(min, value));
+}
+
+export function generateNeutralSwatch(roleColors: GeneratedHarmonyRoleColors): NeutralSwatchResult {
+  const tintSourceHex = pickTintSourceHex(roleColors, roleColors.harmony);
+  const tintSource = parseHexToOklch(tintSourceHex);
+
+  const primary = parseHexToOklch(roleColors.primary.hex);
+
+  const preferGray = tintSource.c < MIN_HUEFUL_CHROMA;
+
+  const hue = roleColors.harmony === 'monochromatic' ? primary.h : tintSource.h;
+  const sourceChroma = roleColors.harmony === 'monochromatic' ? primary.c : tintSource.c;
+  const neutralHue = preferGray ? 0 : normalizeHueDegrees(hue);
+  const neutralChroma = preferGray ? 0 : clampNumber(sourceChroma * 0.06, 0.004, 0.012);
+
+  const neutralKeyColor = oklchToHex({
+    mode: 'oklch',
+    l: 0.6,
+    c: neutralChroma,
+    h: neutralHue,
+  });
+
+  const { swatch, diagnostics } = generateColorSwatch(neutralKeyColor);
+
+  return { neutralKeyColor, neutral: swatch, diagnostics };
+}

package/src/semantics.ts

@@ -0,0 +1,60 @@
+import type { GeneratedColorRole } from './harmony';
+import type { ColorSwatchStep } from './swatches';
+
+export type ThemeColorMode = 'light' | 'dark';
+
+export type SemanticColorToken =
+  | 'background'
+  | 'surface'
+  | 'surfaceRaised'
+  | 'border'
+  | 'divider'
+  | 'text'
+  | 'textMuted'
+  | 'disabledBg'
+  | 'disabledText'
+  | 'brand'
+  | 'brandEmphasis'
+  | 'action'
+  | 'actionEmphasis';
+
+export type SemanticColorRole = 'neutral' | GeneratedColorRole;
+
+export interface SemanticColorReference {
+  role: SemanticColorRole;
+  step: ColorSwatchStep;
+}
+
+export type SemanticColorReferenceMap = Record<SemanticColorToken, SemanticColorReference>;
+
+export const LIGHT_SEMANTIC_COLOR_REFERENCES: SemanticColorReferenceMap = {
+  background: { role: 'neutral', step: 50 },
+  surface: { role: 'neutral', step: 100 },
+  surfaceRaised: { role: 'neutral', step: 50 },
+  border: { role: 'neutral', step: 200 },
+  divider: { role: 'neutral', step: 200 },
+  text: { role: 'neutral', step: 900 },
+  textMuted: { role: 'neutral', step: 700 },
+  disabledBg: { role: 'neutral', step: 200 },
+  disabledText: { role: 'neutral', step: 500 },
+  brand: { role: 'primary', step: 600 },
+  brandEmphasis: { role: 'primary', step: 700 },
+  action: { role: 'primary', step: 600 },
+  actionEmphasis: { role: 'primary', step: 700 },
+};
+
+export const DARK_SEMANTIC_COLOR_REFERENCES: SemanticColorReferenceMap = {
+  background: { role: 'neutral', step: 950 },
+  surface: { role: 'neutral', step: 900 },
+  surfaceRaised: { role: 'neutral', step: 900 },
+  border: { role: 'neutral', step: 800 },
+  divider: { role: 'neutral', step: 800 },
+  text: { role: 'neutral', step: 50 },
+  textMuted: { role: 'neutral', step: 200 },
+  disabledBg: { role: 'neutral', step: 800 },
+  disabledText: { role: 'neutral', step: 500 },
+  brand: { role: 'primary', step: 400 },
+  brandEmphasis: { role: 'primary', step: 300 },
+  action: { role: 'primary', step: 400 },
+  actionEmphasis: { role: 'primary', step: 300 },
+};

package/src/swatches.ts

@@ -0,0 +1,151 @@
+import type { HexColor } from './hex';
+import { deltaEoklch, oklchToHex, parseHexToOklch } from './internal-culori';
+
+export const COLOR_SWATCH_STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950] as const;
+export type ColorSwatchStep = (typeof COLOR_SWATCH_STEPS)[number];
+
+export const COLOR_SWATCH_BASE_STEP = 500 as const;
+
+export type ColorSwatch = Record<ColorSwatchStep, HexColor>;
+
+export type ColorSwatchWarningCode =
+  | 'weak_step'
+  | 'weak_adjacent_delta'
+  | 'limited_lightness_range';
+
+export interface ColorSwatchWarning {
+  code: ColorSwatchWarningCode;
+  step?: ColorSwatchStep;
+  message: string;
+  deltaEFromBase?: number;
+}
+
+export interface ColorSwatchDiagnostics {
+  isUsable: boolean;
+  warnings: readonly ColorSwatchWarning[];
+  minAdjacentDelta: number;
+  maxAdjacentDelta: number;
+  lightnessRange: {
+    min: number;
+    max: number;
+  };
+}
+
+const BASELINE_LIGHTNESS_BY_STEP: Record<ColorSwatchStep, number> = {
+  50: 0.985,
+  100: 0.967,
+  200: 0.928,
+  300: 0.872,
+  400: 0.707,
+  500: 0.551,
+  600: 0.446,
+  700: 0.373,
+  800: 0.278,
+  900: 0.21,
+  950: 0.13,
+};
+
+const MIN_USABLE_ADJACENT_DELTA = 0.012;
+const MIN_USABLE_LIGHTNESS_RANGE = 0.35;
+
+function clamp01(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(1, Math.max(0, value));
+}
+
+function chromaMultiplierForStep(step: ColorSwatchStep): number {
+  if (step <= 200) return 0.55;
+  if (step <= 400) return 0.75;
+  if (step === COLOR_SWATCH_BASE_STEP) return 1;
+  if (step <= 700) return 0.9;
+  return 0.8;
+}
+
+export function generateColorSwatch(baseColor: HexColor): {
+  swatch: ColorSwatch;
+  diagnostics: ColorSwatchDiagnostics;
+} {
+  const baseOklch = parseHexToOklch(baseColor);
+  const baseOffset = baseOklch.l - BASELINE_LIGHTNESS_BY_STEP[COLOR_SWATCH_BASE_STEP];
+
+  const warnings: ColorSwatchWarning[] = [];
+  const swatch = {} as ColorSwatch;
+  const lightnessEntries: number[] = [];
+  const adjacentDeltas: number[] = [];
+
+  for (const step of COLOR_SWATCH_STEPS) {
+    if (step === COLOR_SWATCH_BASE_STEP) {
+      swatch[step] = baseColor;
+      lightnessEntries.push(baseOklch.l);
+      continue;
+    }
+
+    const targetL = clamp01(BASELINE_LIGHTNESS_BY_STEP[step] + baseOffset);
+    const targetC = clamp01(baseOklch.c * chromaMultiplierForStep(step));
+    const target = { ...baseOklch, l: targetL, c: targetC };
+    const hex = oklchToHex(target);
+    swatch[step] = hex;
+
+    const candidateOklch = parseHexToOklch(hex);
+    lightnessEntries.push(candidateOklch.l);
+
+    const deltaEFromBase = deltaEoklch(baseOklch, candidateOklch);
+    if (deltaEFromBase < 0.02) {
+      warnings.push({
+        code: 'weak_step',
+        step,
+        deltaEFromBase,
+        message: `Swatch step ${step} is visually close to the base color.`,
+      });
+    }
+  }
+
+  for (let index = 1; index < COLOR_SWATCH_STEPS.length; index++) {
+    const previousStep = COLOR_SWATCH_STEPS[index - 1];
+    const currentStep = COLOR_SWATCH_STEPS[index];
+    if (previousStep === undefined || currentStep === undefined) continue;
+
+    const previous = parseHexToOklch(swatch[previousStep]);
+    const current = parseHexToOklch(swatch[currentStep]);
+    const adjacentDelta = deltaEoklch(previous, current);
+    adjacentDeltas.push(adjacentDelta);
+
+    if (adjacentDelta < MIN_USABLE_ADJACENT_DELTA) {
+      warnings.push({
+        code: 'weak_adjacent_delta',
+        step: currentStep,
+        deltaEFromBase: adjacentDelta,
+        message: `Swatch step ${currentStep} is visually close to adjacent step ${previousStep}.`,
+      });
+    }
+  }
+
+  const minAdjacentDelta = Math.min(...adjacentDeltas);
+  const maxAdjacentDelta = Math.max(...adjacentDeltas);
+  const minLightness = Math.min(...lightnessEntries);
+  const maxLightness = Math.max(...lightnessEntries);
+  const lightnessRange = maxLightness - minLightness;
+
+  if (lightnessRange < MIN_USABLE_LIGHTNESS_RANGE) {
+    warnings.push({
+      code: 'limited_lightness_range',
+      message: 'Generated swatch has a limited lightness range.',
+    });
+  }
+
+  return {
+    swatch,
+    diagnostics: {
+      isUsable:
+        minAdjacentDelta >= MIN_USABLE_ADJACENT_DELTA &&
+        lightnessRange >= MIN_USABLE_LIGHTNESS_RANGE,
+      warnings,
+      minAdjacentDelta,
+      maxAdjacentDelta,
+      lightnessRange: {
+        min: minLightness,
+        max: maxLightness,
+      },
+    },
+  };
+}

package/src/theme-colors.ts

@@ -0,0 +1,77 @@
+import { type GeneratedHarmonyRoleColors, generateHarmonyRoleColors } from './harmony';
+import type { HexColor } from './hex';
+import { parseHexColorOrThrow } from './hex';
+import { type GeneratedNeutralMetadata, generateNeutralSwatch } from './neutral';
+import { type ColorSwatch, generateColorSwatch } from './swatches';
+
+export interface ThemeModeColorInput {
+  primaryColor: string;
+  harmony: GeneratedHarmonyRoleColors['harmony'];
+}
+
+export interface ThemeColorInput {
+  light: ThemeModeColorInput;
+  dark: ThemeModeColorInput;
+}
+
+export interface GeneratedThemeSwatches {
+  primary: ColorSwatch;
+  secondary?: ColorSwatch;
+  tertiary?: ColorSwatch;
+  quaternary?: ColorSwatch;
+  neutral: ColorSwatch;
+}
+
+export interface GeneratedThemeModeColors {
+  harmonyRoleColors: GeneratedHarmonyRoleColors;
+  swatches: GeneratedThemeSwatches;
+  neutral: GeneratedNeutralMetadata;
+}
+
+export function getThemeModePrimaryHex(mode: ThemeModeColorInput): HexColor {
+  return parseHexColorOrThrow(mode.primaryColor);
+}
+
+export function generateThemeModeColors(mode: ThemeModeColorInput): GeneratedThemeModeColors {
+  const primaryHex = getThemeModePrimaryHex(mode);
+  const harmonyRoleColors = generateHarmonyRoleColors(primaryHex, mode.harmony);
+
+  const primarySwatch = generateColorSwatch(harmonyRoleColors.primary.hex).swatch;
+  const secondarySwatch = harmonyRoleColors.secondary
+    ? generateColorSwatch(harmonyRoleColors.secondary.hex).swatch
+    : undefined;
+  const tertiarySwatch = harmonyRoleColors.tertiary
+    ? generateColorSwatch(harmonyRoleColors.tertiary.hex).swatch
+    : undefined;
+  const quaternarySwatch = harmonyRoleColors.quaternary
+    ? generateColorSwatch(harmonyRoleColors.quaternary.hex).swatch
+    : undefined;
+
+  const neutral = generateNeutralSwatch(harmonyRoleColors);
+  const swatches: GeneratedThemeSwatches = {
+    primary: primarySwatch,
+    neutral: neutral.neutral,
+    ...(secondarySwatch ? { secondary: secondarySwatch } : {}),
+    ...(tertiarySwatch ? { tertiary: tertiarySwatch } : {}),
+    ...(quaternarySwatch ? { quaternary: quaternarySwatch } : {}),
+  };
+
+  return {
+    harmonyRoleColors,
+    swatches,
+    neutral: {
+      neutralKeyColor: neutral.neutralKeyColor,
+      diagnostics: neutral.diagnostics,
+    },
+  };
+}
+
+export function generateThemeColors(theme: ThemeColorInput): {
+  light: GeneratedThemeModeColors;
+  dark: GeneratedThemeModeColors;
+} {
+  return {
+    light: generateThemeModeColors(theme.light),
+    dark: generateThemeModeColors(theme.dark),
+  };
+}