@rafters/color-utils 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ezmode Games
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# @rafters/color-utils
+
+> OKLCH-first color math for the Rafters design system.
+
+Every color in Rafters is OKLCH before it is anything else. This package holds
+the math that acts on it: conversion, perceptual analysis, accessibility scoring,
+gamut awareness, harmony and semantic generation, deterministic naming, and the
+builder that assembles a full color value from a single seed. Parsing from CSS
+and formatting back to it exist for interoperability, but the algorithms work in
+OKLCH because that is where the perceptual results hold up.
+
+## Install
+
+Published as TypeScript source; consumers need a bundler or tsx/vite. Plain
+`node` cannot import it.
+
+```bash
+pnpm add @rafters/color-utils
+```
+
+Import from another package:
+
+```ts
+import {
+  hexToOKLCH,
+  oklchToCSS,
+  roundOKLCH,
+  buildColorValue,
+  getGamutTier,
+  generateHarmony,
+  generateColorName,
+  calculateWCAGContrast,
+} from '@rafters/color-utils';
+```
+
+## What's inside
+
+### Conversion (`conversion.ts`)
+
+- `hexToOKLCH(hex)` — parse a hex or CSS color into OKLCH.
+- `tryParseColor(input)` — parse without throwing; returns null on a bad string.
+- `oklchToCSS(oklch, options?)` — format as a CSS `oklch()` string.
+- `roundOKLCH(oklch)` — normalize and round, so equal colors cache as equal.
+
+```ts
+const o = hexToOKLCH('#0ea5a4');
+oklchToCSS(roundOKLCH(o)); // 'oklch(0.654 0.11 194)'
+```
+
+`oklchToCSS` emits `oklch(L C H)`, or `oklch(L C H / A)` when `alpha` is defined
+and is not 1. `options.precision`, when given, is the number of decimal places
+applied to every emitted channel — L, C, H, and A alike. With no options and no
+alpha the output is the plain three-channel string, unrounded.
+
+```ts
+oklchToCSS({ l: 0.7, c: 0.15, h: 250 });
+// 'oklch(0.7 0.15 250)'
+
+oklchToCSS({ l: 0.7, c: 0.15, h: 250, alpha: 0.5 });
+// 'oklch(0.7 0.15 250 / 0.5)'
+
+oklchToCSS({ l: 0.70001, c: 0.15001, h: 250.001 }, { precision: 2 });
+// 'oklch(0.70 0.15 250.00)'
+
+oklchToCSS({ l: 0.70001, c: 0.15001, h: 250.001, alpha: 0.5001 }, { precision: 3 });
+// 'oklch(0.700 0.150 250.001 / 0.500)'
+```
+
+### Gamut (`gamut.ts`)
+
+A three-tier model built on what displays actually support: `srgb` shows
+everywhere, `p3` needs a wide-gamut screen, `out` is displayable nowhere.
+
+- `getGamutTier(oklch)` — which tier a color falls in.
+- `isInSRGBGamut(oklch)` / `isInP3Gamut(oklch)` — the two boundary checks.
+- `toNearestGamut(oklch)` — snap an out-of-gamut color into sRGB. Returns
+  `{ color, tier }`: the snapped OKLCH and the tier it landed in.
+- `computeGamutBoundaries(hue, steps?)` — the boundary points a picker draws
+  against.
+
+Boundary checks run through `colorjs.io`, so sRGB and P3 agree with what the
+browser will render.
+
+### Accessibility (`accessibility.ts`)
+
+- `calculateWCAGContrast(fg, bg)` — the WCAG contrast ratio.
+- `calculateAPCAContrast(fg, bg)` — the APCA score, for modern contrast work.
+- `generateAccessibilityMetadata(scale)` / `rebakeAccessibility(value)` — precompute
+  the pass/fail matrix for a scale, and rebuild it after an edit.
+
+```ts
+calculateWCAGContrast(o, hexToOKLCH('#ffffff'));
+```
+
+### Analysis (`analysis.ts`)
+
+- `isLightColor(color)` — light or dark, with a chroma adjustment.
+- `getColorTemperature(color)` — warm, cool, or neutral from hue and chroma. The
+  package's only temperature classifier: everything that needs the verdict calls
+  this one.
+- `calculateAtmosphericWeight(color)` / `calculatePerceptualWeight(color)` —
+  perceptual weight, for background-to-foreground role and layout balance.
+
+### Manipulation (`manipulation.ts`)
+
+- `adjustHue(color, degrees)` — rotate the hue, normalized back into 0-360.
+
+### Harmony and scales (`harmony.ts`)
+
+- `generateHarmony(base)` — hue rotations: complementary, triadic, analogous,
+  tetradic, split-complementary, monochromatic.
+- `generateOKLCHScale(base)` — an accessible 50 to 950 scale tuned for contrast.
+
+### Semantic selection (`semantic.ts`)
+
+Purpose-driven pair finding over a color value. Pairs are found in light mode,
+then inverted as a unit for dark mode so the relationship survives.
+
+- `semanticFor(family, { name? })` — open a selection context over one color
+  family. The returned context carries `.pair(request)` for a single use,
+  `.states(from, dark?)` for the whole state ladder, and `.invert(pair)` for the
+  dark-mode counterpart.
+- `statusAnchor(role, seed)` — the one OKLCH anchor for a status role
+  (`destructive`, `success`, `warning`, `info`), with chroma derived from the seed.
+- `generateSemanticColorSuggestions(base)` — seed-derived semantic palettes
+  (danger, success, warning, info), three variants per role.
+- `STATE_USES`, `SemanticSelectionError`, and the `Pair*` types.
+
+### Color wheel and builder (`color-wheel.ts`, `builder.ts`)
+
+- `buildColorValue(oklch, options)` — assemble a full color value (scale,
+  harmonies, accessibility) from one OKLCH seed, with pure math and no network.
+- `colorWheel(seed, harmony, options?)` — a complete 11-family semantic system
+  from a single seed. `harmony` is required and names the relationship
+  (`complementary`, `triadic`, `tetradic`, `analogous`, `split-complementary`).
+
+### Scale positions (`scale-positions.ts`)
+
+- `SCALE_POSITIONS` — the canonical labels (`50`, `100`, ... `950`).
+- `POSITION_TO_INDEX` — the inverse lookup. Vocabulary only; selection lives in
+  `semantic.ts`.
+
+### Naming (`naming/`)
+
+- `generateColorName(oklch)` / `generateColorNameWithMetadata(oklch)` — a stable,
+  human-readable name from an OKLCH value, chosen by temperature and perceptual
+  weight.
+
+```ts
+generateColorName({ l: 0.65, c: 0.12, h: 230, alpha: 1 }); // 'luminous-true-bay-blue'
+```
+
+The bucket helpers and word lists (`getCBucket`, `getChromaBand`, `HUE_HUBS`,
+`MATERIAL_WORDS`, and the rest) are exported for callers building their own
+naming views.
+
+## Testing
+
+```bash
+pnpm --filter @rafters/color-utils test
+```
+
+## Notes
+
+- OKLCH-first. Conversions exist for interoperability; the math stays in OKLCH.
+- Accessibility scoring is mathematical, and APCA is there for modern contrast
+  evaluation alongside WCAG.
+- Published as TypeScript source. It gains nothing from a build step, but a
+  consumer needs a bundler or tsx/vite to import it — plain `node` cannot.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@rafters/color-utils",
+  "version": "0.2.3",
+  "description": "OKLCH color manipulation utilities for Rafters design system",
+  "homepage": "https://rafters.studio",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rafters-studio/rafters.git",
+    "directory": "packages/color-utils"
+  },
+  "files": [
+    "src",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf .turbo coverage"
+  },
+  "dependencies": {
+    "@rafters/shared": "workspace:*",
+    "apca-w3": "^0.1.9",
+    "colorjs.io": "^0.5.2",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "tsx": "^4.21.0",
+    "typescript": "catalog:",
+    "vitest": "catalog:",
+    "zocker": "catalog:"
+  }
+}

package/src/accessibility.ts

@@ -0,0 +1,277 @@
+/**
+ * Accessibility contrast calculation and compliance checking functions
+ */
+
+import type { ColorValue, OKLCH } from '@rafters/shared';
+import { APCAcontrast, sRGBtoY } from 'apca-w3';
+import Color from 'colorjs.io';
+import { z } from 'zod';
+
+/** White reference color for contrast calculations. */
+export const CONTRAST_WHITE: OKLCH = { l: 1, c: 0, h: 0, alpha: 1 };
+
+/** Black reference color for contrast calculations. */
+export const CONTRAST_BLACK: OKLCH = { l: 0, c: 0, h: 0, alpha: 1 };
+
+/** WCAG 2.1 minimum contrast ratios, by conformance level and text size. */
+const WCAG_CONTRAST_THRESHOLDS = {
+  AA: { normal: 4.5, large: 3.0 },
+  AAA: { normal: 7.0, large: 4.5 },
+} as const;
+
+/**
+ * Breakpoints for ColorValue.accessibility.apca.minFontSize, most demanding
+ * first. This is builder.ts's own two-breakpoint ternary (16px at >=60,
+ * 24px at >=45, 32px otherwise), pulled out so it is encoded once instead of
+ * inline in buildColorValue. It is not a general APCA font-size table -- the
+ * finer-grained small/medium/large breakpoints that once lived in the now
+ * -deleted, uncalled `meetsAPCAStandard` do not appear here; that function
+ * had zero callers repo-wide and its table was never reconciled with this one.
+ */
+const APCA_FONT_SIZE_THRESHOLDS: readonly { minFontSize: number; minContrast: number }[] = [
+  { minFontSize: 16, minContrast: 60 },
+  { minFontSize: 24, minContrast: 45 },
+  { minFontSize: 32, minContrast: 0 },
+];
+
+/**
+ * Smallest font size (in px) that stays readable at the given APCA contrast,
+ * per ColorValue.accessibility.apca.minFontSize's existing breakpoints (see
+ * APCA_FONT_SIZE_THRESHOLDS). Contrast sign is irrelevant -- APCA reports
+ * polarity, magnitude is what carries legibility.
+ */
+export function minFontSizeForAPCA(contrast: number): number {
+  const magnitude = Math.abs(contrast);
+  for (const { minFontSize, minContrast } of APCA_FONT_SIZE_THRESHOLDS) {
+    if (magnitude >= minContrast) return minFontSize;
+  }
+  // Unreachable: the last row has minContrast 0. Kept for exhaustiveness.
+  return 32;
+}
+
+/**
+ * Convert OKLCH to relative luminance for WCAG calculations
+ */
+function getRelativeLuminance(oklch: OKLCH): number {
+  const color = new Color('oklch', [oklch.l, oklch.c, oklch.h]);
+  const srgb = color.to('srgb');
+
+  // WCAG formula for relative luminance
+  const toLinear = (val: number): number => {
+    if (val <= 0.03928) {
+      return val / 12.92;
+    }
+    return ((val + 0.055) / 1.055) ** 2.4;
+  };
+
+  const r = toLinear(srgb.r);
+  const g = toLinear(srgb.g);
+  const b = toLinear(srgb.b);
+
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/**
+ * Calculate WCAG 2.1 contrast ratio between two colors
+ */
+export function calculateWCAGContrast(foreground: OKLCH, background: OKLCH): number {
+  const l1 = getRelativeLuminance(foreground);
+  const l2 = getRelativeLuminance(background);
+
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Calculate APCA contrast for modern accessibility
+ * Uses the official APCA algorithm via apca-w3 library
+ */
+export function calculateAPCAContrast(foreground: OKLCH, background: OKLCH): number {
+  // Convert OKLCH to RGB arrays for APCA
+  const foregroundColor = new Color('oklch', [foreground.l, foreground.c, foreground.h]);
+  const backgroundColorObj = new Color('oklch', [background.l, background.c, background.h]);
+
+  const fgRgb = foregroundColor.to('srgb');
+  const bgRgb = backgroundColorObj.to('srgb');
+
+  // Convert to 0-255 RGB values for apca-w3
+  const fgR = Math.max(0, Math.min(255, (fgRgb.r || 0) * 255));
+  const fgG = Math.max(0, Math.min(255, (fgRgb.g || 0) * 255));
+  const fgB = Math.max(0, Math.min(255, (fgRgb.b || 0) * 255));
+  const bgR = Math.max(0, Math.min(255, (bgRgb.r || 0) * 255));
+  const bgG = Math.max(0, Math.min(255, (bgRgb.g || 0) * 255));
+  const bgB = Math.max(0, Math.min(255, (bgRgb.b || 0) * 255));
+
+  // Calculate luminance values
+  const fgY = sRGBtoY([fgR, fgG, fgB]);
+  const bgY = sRGBtoY([bgR, bgG, bgB]);
+
+  // Use official APCA calculation
+  const result = APCAcontrast(fgY, bgY);
+  return typeof result === 'number' ? result : 0;
+}
+
+/**
+ * Check if color pair meets WCAG contrast standards.
+ * Module-private: the pass/fail matrices below are its only consumers.
+ */
+function meetsWCAGStandard(
+  foreground: OKLCH,
+  background: OKLCH,
+  level: 'AA' | 'AAA',
+  textSize: 'normal' | 'large',
+): boolean {
+  const contrast = calculateWCAGContrast(foreground, background);
+  return contrast >= WCAG_CONTRAST_THRESHOLDS[level][textSize];
+}
+
+/** Pre-computed pairs of scale indices that pass a contrast standard. */
+const ContrastPairsSchema = z.object({
+  normal: z.array(z.array(z.number())),
+  large: z.array(z.array(z.number())),
+});
+
+/** Pre-computed scale indices that pass on a single-color background. */
+const BackgroundComplianceSchema = z.object({
+  aa: z.array(z.number()),
+  aaa: z.array(z.number()),
+});
+
+/**
+ * Pre-computed accessibility metadata for a color scale. Indices reference
+ * positions in the source scale array.
+ */
+export const AccessibilityMetadataSchema = z.object({
+  wcagAA: ContrastPairsSchema,
+  wcagAAA: ContrastPairsSchema,
+  onWhite: BackgroundComplianceSchema,
+  onBlack: BackgroundComplianceSchema,
+});
+export type AccessibilityMetadata = z.infer<typeof AccessibilityMetadataSchema>;
+
+/**
+ * Generate pre-computed accessibility metadata for a color scale
+ * Eliminates expensive on-demand contrast calculations by storing all valid pairs as indices
+ */
+export function generateAccessibilityMetadata(scale: OKLCH[]): AccessibilityMetadata {
+  if (!scale || scale.length === 0) {
+    // Return empty metadata for invalid scales
+    return {
+      wcagAA: { normal: [], large: [] },
+      wcagAAA: { normal: [], large: [] },
+      onWhite: { aa: [], aaa: [] },
+      onBlack: { aa: [], aaa: [] },
+    };
+  }
+
+  const metadata: AccessibilityMetadata = {
+    wcagAA: { normal: [], large: [] },
+    wcagAAA: { normal: [], large: [] },
+    onWhite: { aa: [], aaa: [] },
+    onBlack: { aa: [], aaa: [] },
+  };
+
+  // Check all pairs within the scale
+  for (let i = 0; i < scale.length; i++) {
+    for (let j = 0; j < scale.length; j++) {
+      if (i === j) continue; // Skip same color pairs
+
+      const color1 = scale[i];
+      const color2 = scale[j];
+
+      // Skip invalid OKLCH values
+      if (!color1 || !color2 || typeof color1.l !== 'number' || typeof color2.l !== 'number') {
+        continue;
+      }
+
+      // Check WCAG AA compliance
+      if (meetsWCAGStandard(color1, color2, 'AA', 'normal')) {
+        metadata.wcagAA.normal.push([i, j]);
+      }
+      if (meetsWCAGStandard(color1, color2, 'AA', 'large')) {
+        metadata.wcagAA.large.push([i, j]);
+      }
+
+      // Check WCAG AAA compliance
+      if (meetsWCAGStandard(color1, color2, 'AAA', 'normal')) {
+        metadata.wcagAAA.normal.push([i, j]);
+      }
+      if (meetsWCAGStandard(color1, color2, 'AAA', 'large')) {
+        metadata.wcagAAA.large.push([i, j]);
+      }
+    }
+
+    // Check against white background
+    const colorForWhite = scale[i];
+    if (colorForWhite && typeof colorForWhite.l === 'number') {
+      if (meetsWCAGStandard(colorForWhite, CONTRAST_WHITE, 'AA', 'normal')) {
+        metadata.onWhite.aa.push(i);
+      }
+      if (meetsWCAGStandard(colorForWhite, CONTRAST_WHITE, 'AAA', 'normal')) {
+        metadata.onWhite.aaa.push(i);
+      }
+    }
+
+    // Check against black background
+    const colorForBlack = scale[i];
+    if (colorForBlack && typeof colorForBlack.l === 'number') {
+      if (meetsWCAGStandard(colorForBlack, CONTRAST_BLACK, 'AA', 'normal')) {
+        metadata.onBlack.aa.push(i);
+      }
+      if (meetsWCAGStandard(colorForBlack, CONTRAST_BLACK, 'AAA', 'normal')) {
+        metadata.onBlack.aaa.push(i);
+      }
+    }
+  }
+
+  return metadata;
+}
+
+/**
+ * Assemble the WCAG half of ColorValue.accessibility for a scale: pair
+ * matrices plus on-white/on-black ratios and pass flags for a reference
+ * color. Shared by buildColorValue (which adds APCA on top) and
+ * rebakeAccessibility -- one assembly, two consumers, no drift.
+ */
+export function assembleWcagAccessibility(
+  scale: readonly OKLCH[],
+  reference: OKLCH,
+): Pick<NonNullable<ColorValue['accessibility']>, 'wcagAA' | 'wcagAAA' | 'onWhite' | 'onBlack'> {
+  const meta = generateAccessibilityMetadata([...scale]);
+  const onWhiteRatio = calculateWCAGContrast(reference, CONTRAST_WHITE);
+  const onBlackRatio = calculateWCAGContrast(reference, CONTRAST_BLACK);
+  return {
+    wcagAA: meta.wcagAA,
+    wcagAAA: meta.wcagAAA,
+    onWhite: {
+      wcagAA: onWhiteRatio >= WCAG_CONTRAST_THRESHOLDS.AA.normal,
+      wcagAAA: onWhiteRatio >= WCAG_CONTRAST_THRESHOLDS.AAA.normal,
+      contrastRatio: onWhiteRatio,
+      aa: meta.onWhite.aa,
+      aaa: meta.onWhite.aaa,
+    },
+    onBlack: {
+      wcagAA: onBlackRatio >= WCAG_CONTRAST_THRESHOLDS.AA.normal,
+      wcagAAA: onBlackRatio >= WCAG_CONTRAST_THRESHOLDS.AAA.normal,
+      contrastRatio: onBlackRatio,
+      aa: meta.onBlack.aa,
+      aaa: meta.onBlack.aaa,
+    },
+  };
+}
+
+/**
+ * Re-derive accessibility metadata for a ColorValue whose scale changed.
+ * A family value supplied without its WCAG pair matrices would starve the
+ * contrast/state/invert selection downstream -- this guard re-bakes them.
+ * No-op for values without a scale. (Moved from the removed CLI set command;
+ * the studio API mutation path is the consumer. #1643)
+ */
+export function rebakeAccessibility(value: ColorValue): ColorValue {
+  if (!('scale' in value) || !Array.isArray(value.scale)) return value;
+  const reference = value.scale[5] ?? value.scale[0];
+  if (!reference) return value;
+  return { ...value, accessibility: assembleWcagAccessibility(value.scale, reference) };
+}

package/src/analysis.ts

@@ -0,0 +1,166 @@
+/**
+ * Color analysis functions for perceptual color properties
+ */
+
+import type { OKLCH } from '@rafters/shared';
+import { clamp01, normalizeHue, VIVID_CHROMA_CAP } from './internal/math.js';
+
+/**
+ * Determine if color is light or dark based on perceptual lightness
+ * Uses OKLCH lightness with adjustments for chroma
+ */
+export function isLightColor(color: OKLCH): boolean {
+  // Base threshold at 50% lightness
+  let threshold = 0.5;
+
+  // Adjust threshold based on chroma
+  // High chroma colors appear darker due to the Helmholtz-Kohlrausch effect
+  if (color.c > 0.15) {
+    threshold += color.c * 0.3; // Increase threshold for high chroma
+  }
+
+  // Very low chroma colors are essentially gray, use simple lightness
+  if (color.c < 0.05) {
+    threshold = 0.5;
+  }
+
+  return color.l > threshold;
+}
+
+/**
+ * Calculate color temperature (warm/cool/neutral).
+ * Based on hue angle and chroma intensity.
+ *
+ * This is the package's only temperature classifier: everything that needs a
+ * warm/cool/neutral verdict (including calculateAtmosphericWeight below) calls
+ * it, so two parts of the same ColorValue can never disagree again.
+ */
+export function getColorTemperature(color: OKLCH): 'warm' | 'cool' | 'neutral' {
+  // Very low chroma colors are neutral regardless of hue
+  if (color.c < 0.04) {
+    return 'neutral';
+  }
+
+  const hue = normalizeHue(color.h);
+
+  // Define temperature ranges based on color theory
+  // Warm: reds, oranges, yellows, warm purples
+  // Cool: greens, cyans, blues, cool purples
+
+  if (
+    (hue >= 0 && hue <= 90) || // Red to yellow
+    (hue >= 315 && hue < 360) // Red-purple to red
+  ) {
+    return 'warm';
+  }
+
+  if (hue >= 150 && hue <= 270) {
+    // Green-cyan to blue-purple
+    return 'cool';
+  }
+
+  // Boundary zones (yellow-green and purple-red) depend on specific hue
+  if (hue > 90 && hue < 150) {
+    // Yellow-green to green
+    // More yellow = warm, more green = cool
+    return hue < 120 ? 'warm' : 'cool';
+  }
+
+  if (hue > 270 && hue < 315) {
+    // Purple to red-purple
+    // More blue = cool, more red = warm
+    return hue > 290 ? 'warm' : 'cool';
+  }
+
+  // Fallback for edge cases
+  return 'neutral';
+}
+
+/**
+ * Colors get cooler and lighter with distance
+ * Applied to UI: background colors should be cooler/lighter, foreground warmer/darker
+ *
+ * Temperature comes from getColorTemperature -- the same verdict that lands in
+ * ColorValue.analysis.temperature -- so the two never contradict each other.
+ */
+export function calculateAtmosphericWeight(color: OKLCH): {
+  distanceWeight: number; // 0 = background, 1 = foreground
+  temperature: 'warm' | 'neutral' | 'cool';
+  atmosphericRole: 'background' | 'midground' | 'foreground';
+} {
+  const temperature = getColorTemperature(color);
+
+  const lightnessWeight = color.l;
+
+  let distanceWeight = 0;
+
+  if (temperature === 'warm') {
+    distanceWeight += 0.3;
+  } else if (temperature === 'cool') {
+    distanceWeight -= 0.2;
+  }
+
+  distanceWeight += (1 - lightnessWeight) * 0.4;
+  distanceWeight += color.c * 1.5;
+
+  distanceWeight = clamp01(distanceWeight);
+
+  let atmosphericRole: 'background' | 'midground' | 'foreground';
+  if (distanceWeight < 0.3) atmosphericRole = 'background';
+  else if (distanceWeight < 0.7) atmosphericRole = 'midground';
+  else atmosphericRole = 'foreground';
+
+  return { distanceWeight, temperature, atmosphericRole };
+}
+
+/**
+ * some colors feel "heavier" than others
+ * Used for visual balance in UI layouts
+ */
+export function calculatePerceptualWeight(color: OKLCH): {
+  weight: number; // 0-1, higher = more visual weight
+  density: 'light' | 'medium' | 'heavy';
+  balancingRecommendation: string;
+} {
+  const hue = color.h;
+  let hueWeight = 0.5;
+
+  if (hue >= 345 || hue <= 15)
+    hueWeight = 0.9; // Red - heaviest
+  else if (hue <= 45)
+    hueWeight = 0.8; // Red-Orange
+  else if (hue <= 75)
+    hueWeight = 0.6; // Orange-Yellow
+  else if (hue <= 105)
+    hueWeight = 0.4; // Yellow-Green
+  else if (hue <= 165)
+    hueWeight = 0.3; // Green - lightest feeling
+  else if (hue <= 225)
+    hueWeight = 0.2; // Blue - very light feeling
+  else if (hue <= 285)
+    hueWeight = 0.35; // Blue-Purple
+  else hueWeight = 0.5; // Purple-Red
+
+  const lightnessWeight = 1 - color.l;
+  const chromaWeight = Math.min(1, color.c / VIVID_CHROMA_CAP);
+
+  const weight = lightnessWeight * 0.4 + chromaWeight * 0.35 + hueWeight * 0.25;
+
+  let density: 'light' | 'medium' | 'heavy';
+
+  if (weight < 0.3) {
+    density = 'light';
+  } else if (weight < 0.7) {
+    density = 'medium';
+  } else {
+    density = 'heavy';
+  }
+
+  const balancingRecommendation = 'Balanced weight';
+
+  return {
+    weight,
+    density,
+    balancingRecommendation,
+  };
+}