@rafters/color-utils 0.2.3

package/src/harmony.ts

@@ -0,0 +1,194 @@
+/**
+ * Harmony generation for design systems using pure OKLCH hue rotation.
+ *
+ * Rule: harmonies are PURE HUE ROTATIONS. L and C are never mutated.
+ * Only H changes. Every output goes through toNearestGamut() then roundOKLCH().
+ */
+
+import type { ColorHarmonies, OKLCH } from '@rafters/shared';
+import { roundOKLCH } from './conversion.js';
+import { clampColor } from './gamut.js';
+import { adjustHue } from './manipulation.js';
+import { POSITION_TO_INDEX, SCALE_POSITIONS } from './scale-positions.js';
+
+/**
+ * Generate pure OKLCH harmony arrays from a base color.
+ *
+ * Counts (per the spec):
+ * - complementary: 1 color (+180)
+ * - triadic: 3 colors (base, +120, +240)
+ * - analogous: 6 colors (-45, -30, -15, +15, +30, +45)
+ * - tetradic: 4 colors (base, +90, +180, +270)
+ * - splitComplementary: 3 colors (base, +150, +210)
+ * - monochromatic: 6 colors (same hue, L steps at 0.15/0.30/0.45/0.60/0.75/0.90,
+ *     chroma reduced at extremes)
+ *
+ * L and C are preserved exactly from the base color in all hue-rotation harmonies.
+ */
+export function generateHarmony(baseColor: OKLCH): ColorHarmonies {
+  const base = clampColor(baseColor);
+
+  // complementary: 1 color at +180
+  const complementary = clampColor(adjustHue(baseColor, 180));
+
+  // triadic: base, +120, +240
+  const triadic: OKLCH[] = [
+    base,
+    clampColor(adjustHue(baseColor, 120)),
+    clampColor(adjustHue(baseColor, 240)),
+  ];
+
+  // analogous: -45, -30, -15, +15, +30, +45
+  const analogous: OKLCH[] = [
+    clampColor(adjustHue(baseColor, -45)),
+    clampColor(adjustHue(baseColor, -30)),
+    clampColor(adjustHue(baseColor, -15)),
+    clampColor(adjustHue(baseColor, 15)),
+    clampColor(adjustHue(baseColor, 30)),
+    clampColor(adjustHue(baseColor, 45)),
+  ];
+
+  // tetradic: base, +90, +180, +270
+  const tetradic: OKLCH[] = [
+    base,
+    clampColor(adjustHue(baseColor, 90)),
+    clampColor(adjustHue(baseColor, 180)),
+    clampColor(adjustHue(baseColor, 270)),
+  ];
+
+  // splitComplementary: base, +150, +210
+  const splitComplementary: OKLCH[] = [
+    base,
+    clampColor(adjustHue(baseColor, 150)),
+    clampColor(adjustHue(baseColor, 210)),
+  ];
+
+  // monochromatic: 6 steps at fixed L values, same H, chroma reduced at extremes
+  const MONO_LIGHTNESS = [0.15, 0.3, 0.45, 0.6, 0.75, 0.9] as const;
+  const monochromatic: OKLCH[] = MONO_LIGHTNESS.map((l) => {
+    // Reduce chroma at extreme ends to avoid gamut clipping artifacts
+    const c = l <= 0.15 || l >= 0.9 ? baseColor.c * 0.5 : baseColor.c;
+    return clampColor({ ...baseColor, l, c });
+  });
+
+  return {
+    complementary,
+    triadic,
+    analogous,
+    tetradic,
+    splitComplementary,
+    monochromatic,
+  };
+}
+
+/**
+ * Validate if a color is suitable for scale generation
+ * Too light or too dark colors don't generate useful scales
+ */
+function validateScaleGeneration(baseColor: OKLCH): {
+  isValid: boolean;
+  reason?: string;
+  suggestedLightness?: number;
+} {
+  const l = baseColor.l;
+
+  if (l > 0.85) {
+    return {
+      isValid: false,
+      reason: 'Color too light for scale generation',
+      suggestedLightness: 0.7,
+    };
+  }
+
+  if (l < 0.15) {
+    return {
+      isValid: false,
+      reason: 'Color too dark for scale generation',
+      suggestedLightness: 0.4,
+    };
+  }
+
+  return { isValid: true };
+}
+
+/**
+ * Generate lightness progression using mathematical functions.
+ * Base color positioned at 600, with 6 lighter steps above + 4 darker + 950.
+ * Power curve (t^0.8) for tints creates natural spacing weighted toward white.
+ * Linear progression for shades keeps darkening predictable.
+ */
+function generateLightnessProgression(baseLightness: number): Record<string, number> {
+  const MAX_LIGHT = 0.95;
+  const MIN_DARK = 0.05;
+
+  const positions = SCALE_POSITIONS;
+  const baseIndex = POSITION_TO_INDEX['600'] ?? 6;
+
+  const lightness: Record<string, number> = {};
+
+  for (let i = 0; i < baseIndex; i++) {
+    const stepsFromBase = baseIndex - i;
+    const totalLighterSteps = baseIndex;
+
+    const t = (stepsFromBase / totalLighterSteps) ** 0.8;
+    const calculatedL = baseLightness + (MAX_LIGHT - baseLightness) * t;
+
+    const pos = positions[i];
+    if (pos !== undefined) lightness[pos] = Math.min(MAX_LIGHT, calculatedL);
+  }
+
+  lightness['600'] = baseLightness;
+
+  for (let i = baseIndex + 1; i < positions.length; i++) {
+    const stepsFromBase = i - baseIndex;
+    const totalDarkerSteps = positions.length - 1 - baseIndex;
+
+    const t = stepsFromBase / totalDarkerSteps;
+    const darkenAmount = (baseLightness - MIN_DARK) * t;
+    const calculatedL = Math.max(MIN_DARK, baseLightness - darkenAmount);
+
+    const pos = positions[i];
+    if (pos !== undefined) lightness[pos] = calculatedL;
+  }
+
+  return lightness;
+}
+
+/**
+ * Generate OKLCH color scale from base color.
+ * Creates 50-950 scale with mathematical lightness progression anchored at 600.
+ * Chroma reduced only at extreme lightness to avoid perceptual artifacts.
+ */
+export function generateOKLCHScale(baseColor: OKLCH): Record<string, OKLCH> {
+  const validation = validateScaleGeneration(baseColor);
+
+  if (!validation.isValid) {
+    const adjustedColor = validation.suggestedLightness
+      ? { ...baseColor, l: validation.suggestedLightness }
+      : baseColor;
+    return generateOKLCHScale(adjustedColor);
+  }
+
+  const lightnessSteps = generateLightnessProgression(baseColor.l);
+
+  const scale: Record<string, OKLCH> = {};
+
+  for (const [step, lightness] of Object.entries(lightnessSteps)) {
+    let adjustedChroma = baseColor.c;
+
+    if (lightness > 0.9) {
+      adjustedChroma *= 0.3;
+    } else if (lightness < 0.15) {
+      adjustedChroma *= 0.6;
+    }
+
+    scale[step] = roundOKLCH({
+      l: lightness,
+      c: adjustedChroma,
+      h: baseColor.h,
+      alpha: baseColor.alpha,
+    });
+  }
+
+  return scale;
+}

package/src/index.ts

@@ -0,0 +1,110 @@
+/**
+ * @rafters/color-utils
+ * OKLCH color manipulation utilities for Rafters design system
+ */
+
+// Accessibility
+export {
+  type AccessibilityMetadata,
+  calculateAPCAContrast,
+  calculateWCAGContrast,
+  generateAccessibilityMetadata,
+  rebakeAccessibility,
+} from './accessibility.js';
+
+// Analysis
+export {
+  calculateAtmosphericWeight,
+  calculatePerceptualWeight,
+  getColorTemperature,
+  isLightColor,
+} from './analysis.js';
+
+// Builder
+export { type BuildColorValueOptions, buildColorValue } from './builder.js';
+
+// Color Wheel
+export {
+  type ColorWheelOptions,
+  colorWheel,
+  type HarmonyType,
+  type SemanticColorSystem,
+} from './color-wheel.js';
+
+// Conversion
+export {
+  hexToOKLCH,
+  type OklchToCSSOptions,
+  oklchToCSS,
+  roundOKLCH,
+  tryParseColor,
+} from './conversion.js';
+
+// Gamut
+export {
+  computeGamutBoundaries,
+  type GamutBoundaryPoint,
+  type GamutTier,
+  getGamutTier,
+  isInP3Gamut,
+  isInSRGBGamut,
+  toNearestGamut,
+} from './gamut.js';
+
+// Harmony
+export { generateHarmony, generateOKLCHScale } from './harmony.js';
+
+// Manipulation
+export { adjustHue } from './manipulation.js';
+// Naming
+export {
+  BLUE_HUB,
+  C_BUCKET_COUNT,
+  type ChromaBand,
+  GREEN_HUB,
+  generateColorName,
+  generateColorNameWithMetadata,
+  getAllBuckets,
+  getCBucket,
+  getChromaBand,
+  getExpandedMaterialWord,
+  getHBucket,
+  getLBucket,
+  getLightnessBand,
+  getSubIndex,
+  H_BUCKET_COUNT,
+  HUE_HUBS,
+  type HueCell,
+  type HueHub,
+  type HueMatrix,
+  hasExpandedHub,
+  INTENSITY_WORDS,
+  type IntensityWord,
+  L_BUCKET_COUNT,
+  type LightnessBand,
+  LUMINOSITY_WORDS,
+  type LuminosityWord,
+  MATERIAL_WORDS,
+  type MaterialWord,
+  RED_HUB,
+  TOTAL_COMBINATIONS,
+} from './naming/index.js';
+// Scale positions (vocabulary only; selection lives in semantic.ts)
+export { POSITION_TO_INDEX, SCALE_POSITIONS } from './scale-positions.js';
+
+// Semantic selection (purpose-driven pair finding + seed-derived suggestions, #1636)
+export {
+  generateSemanticColorSuggestions,
+  type Pair,
+  type PairLeg,
+  type PairRequest,
+  type PairStandard,
+  type PairTier,
+  type PairUse,
+  type SemanticContext,
+  SemanticSelectionError,
+  STATE_USES,
+  type StateUse,
+  semanticFor,
+  statusAnchor,
+} from './semantic.js';

package/src/internal/math.ts

@@ -0,0 +1,35 @@
+/**
+ * Internal numeric helpers shared across the package.
+ *
+ * These are the idioms that were repeated inline in half a dozen modules:
+ * clamping a channel, normalizing a hue angle, and the two chroma ceilings.
+ * Not part of the public surface -- nothing here is re-exported from index.ts.
+ */
+
+/** Clamp a value into [min, max]. */
+export function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+/** Clamp a value into [0, 1] -- the range every OKLCH lightness and alpha lives in. */
+export function clamp01(value: number): number {
+  return clamp(value, 0, 1);
+}
+
+/** Normalize a hue angle into [0, 360), handling negative and over-wrapped input. */
+export function normalizeHue(hue: number): number {
+  return ((hue % 360) + 360) % 360;
+}
+
+/**
+ * Upper bound for a chroma search: no OKLCH color in any display gamut we
+ * care about exceeds this, so binary searches and bucket clamps start here.
+ */
+export const MAX_CHROMA = 0.4;
+
+/**
+ * Chroma ceiling for "as vivid as a generated color may get". Deliberately
+ * lower than MAX_CHROMA and deliberately a separate constant: this is a design
+ * cap on generated output, not a bound on what OKLCH can represent.
+ */
+export const VIVID_CHROMA_CAP = 0.3;

package/src/manipulation.ts

@@ -0,0 +1,16 @@
+/**
+ * OKLCH color manipulation functions
+ */
+
+import type { OKLCH } from '@rafters/shared';
+import { normalizeHue } from './internal/math.js';
+
+/**
+ * Adjust the hue of a color by degrees
+ */
+export function adjustHue(color: OKLCH, degrees: number): OKLCH {
+  return {
+    ...color,
+    h: normalizeHue(color.h + degrees),
+  };
+}

package/src/naming/generator.ts

@@ -0,0 +1,161 @@
+/**
+ * Deterministic Color Name Generator
+ *
+ * Generates unique, semantically meaningful color names from OKLCH values.
+ * Uses temperature and perceptual weight to select appropriate word variants.
+ *
+ * Format: {luminosity}-{intensity}-{material}
+ * Examples: "deep-bold-cobalt", "faint-soft-sage", "shadow-whisper"
+ *
+ * Two-tier system:
+ * 1. Expanded hubs: Rich semantic word banks for Red, Green, Blue (more coming)
+ *    - 5 lightness bands × 4 chroma bands × 10 words = 200 words per temp variant
+ *    - Sub-selection uses fractional L/C for maximum uniqueness
+ * 2. Fallback: Original word banks for hues without expanded hubs
+ */
+
+import type { OKLCH } from '@rafters/shared';
+import { calculatePerceptualWeight, getColorTemperature } from '../analysis.js';
+import { getExpandedMaterialWord, hasExpandedHub } from './hue-hubs.js';
+import { getCBucket, getHBucket, getLBucket } from './quantize.js';
+import { INTENSITY_WORDS, LUMINOSITY_WORDS, MATERIAL_WORDS } from './word-banks.js';
+
+// Threshold for considering a color achromatic (no hue word)
+const ACHROMATIC_THRESHOLD = 0.02;
+
+/**
+ * Generate a deterministic color name from OKLCH values
+ *
+ * The name is composed of up to three hyphenated words:
+ * - Luminosity: describes the lightness (shadow, deep, balanced, pale, brilliant, etc.)
+ * - Intensity: describes the chroma/saturation (whisper, bold, fierce, etc.)
+ * - Material: describes the hue (ember, sapphire, sage, etc.)
+ *
+ * Achromatic colors (chroma < 0.02) omit the material word.
+ *
+ * @param oklch - The color in OKLCH format
+ * @returns A hyphenated color name like "luminous-clear-sapphire"
+ */
+export function generateColorName(oklch: OKLCH): string {
+  // Get computed properties for semantic word selection
+  const temperature = getColorTemperature(oklch);
+  const { density } = calculatePerceptualWeight(oklch);
+
+  // Get bucket indices (guaranteed to be within valid ranges by quantize functions)
+  const lBucket = getLBucket(oklch.l);
+  const cBucket = getCBucket(oklch.c);
+  const hBucket = getHBucket(oklch.h);
+
+  // Select words deterministically
+  // Type assertions are safe because bucket functions guarantee valid indices
+  const luminosity = LUMINOSITY_WORDS[lBucket] as string;
+  const intensityBank = INTENSITY_WORDS[density];
+  const intensity = intensityBank[cBucket] as string;
+
+  // Achromatic colors skip the hue/material word
+  if (oklch.c < ACHROMATIC_THRESHOLD) {
+    return `${luminosity}-${intensity}`;
+  }
+
+  // Try expanded hub first (rich semantic word banks with sub-selection)
+  // Falls back to original word banks for hues without expanded hubs
+  let material: string;
+  if (hasExpandedHub(hBucket)) {
+    material = getExpandedMaterialWord(
+      hBucket,
+      lBucket,
+      cBucket,
+      temperature,
+      oklch.l,
+      oklch.c,
+    ) as string;
+  } else {
+    // Fallback to original word banks
+    const materialBank = MATERIAL_WORDS[temperature];
+    material = materialBank[hBucket] as string;
+  }
+
+  return `${luminosity}-${intensity}-${material}`;
+}
+
+/**
+ * Generate a color name with metadata about the generation
+ *
+ * Useful for debugging and understanding why a particular name was chosen.
+ */
+export function generateColorNameWithMetadata(oklch: OKLCH): {
+  name: string;
+  components: {
+    luminosity: string;
+    intensity: string;
+    material: string | null;
+  };
+  buckets: {
+    l: number;
+    c: number;
+    h: number;
+  };
+  modifiers: {
+    temperature: 'warm' | 'cool' | 'neutral';
+    density: 'light' | 'medium' | 'heavy';
+    isAchromatic: boolean;
+    usedExpandedHub: boolean;
+  };
+} {
+  const temperature = getColorTemperature(oklch);
+  const { density } = calculatePerceptualWeight(oklch);
+
+  const lBucket = getLBucket(oklch.l);
+  const cBucket = getCBucket(oklch.c);
+  const hBucket = getHBucket(oklch.h);
+
+  // Type assertions are safe because bucket functions guarantee valid indices
+  const luminosity = LUMINOSITY_WORDS[lBucket] as string;
+  const intensityBank = INTENSITY_WORDS[density];
+  const intensity = intensityBank[cBucket] as string;
+  const isAchromatic = oklch.c < ACHROMATIC_THRESHOLD;
+
+  // Get material word (expanded hub or fallback)
+  let material: string | null = null;
+  let usedExpandedHub = false;
+  if (!isAchromatic) {
+    if (hasExpandedHub(hBucket)) {
+      material = getExpandedMaterialWord(
+        hBucket,
+        lBucket,
+        cBucket,
+        temperature,
+        oklch.l,
+        oklch.c,
+      ) as string;
+      usedExpandedHub = true;
+    } else {
+      const materialBank = MATERIAL_WORDS[temperature];
+      material = materialBank[hBucket] as string;
+    }
+  }
+
+  const name = isAchromatic
+    ? `${luminosity}-${intensity}`
+    : `${luminosity}-${intensity}-${material}`;
+
+  return {
+    name,
+    components: {
+      luminosity,
+      intensity,
+      material,
+    },
+    buckets: {
+      l: lBucket,
+      c: cBucket,
+      h: hBucket,
+    },
+    modifiers: {
+      temperature,
+      density,
+      isAchromatic,
+      usedExpandedHub,
+    },
+  };
+}