@ankhorage/color-theory 0.0.1

package/dist/swatches.js

@@ -0,0 +1,109 @@
+import { deltaEoklch, oklchToHex, parseHexToOklch } from './internal-culori';
+export const COLOR_SWATCH_STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+export const COLOR_SWATCH_BASE_STEP = 500;
+const BASELINE_LIGHTNESS_BY_STEP = {
+    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) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.min(1, Math.max(0, value));
+}
+function chromaMultiplierForStep(step) {
+    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) {
+    const baseOklch = parseHexToOklch(baseColor);
+    const baseOffset = baseOklch.l - BASELINE_LIGHTNESS_BY_STEP[COLOR_SWATCH_BASE_STEP];
+    const warnings = [];
+    const swatch = {};
+    const lightnessEntries = [];
+    const adjacentDeltas = [];
+    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,
+            },
+        },
+    };
+}
+//# sourceMappingURL=swatches.js.map

package/dist/swatches.js.map

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

package/dist/theme-colors.d.ts

@@ -0,0 +1,31 @@
+import { type GeneratedHarmonyRoleColors } from './harmony';
+import type { HexColor } from './hex';
+import { type GeneratedNeutralMetadata } from './neutral';
+import { type ColorSwatch } 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 declare function getThemeModePrimaryHex(mode: ThemeModeColorInput): HexColor;
+export declare function generateThemeModeColors(mode: ThemeModeColorInput): GeneratedThemeModeColors;
+export declare function generateThemeColors(theme: ThemeColorInput): {
+    light: GeneratedThemeModeColors;
+    dark: GeneratedThemeModeColors;
+};
+//# sourceMappingURL=theme-colors.d.ts.map

package/dist/theme-colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-colors.d.ts","sourceRoot":"","sources":["../src/theme-colors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,0BAA0B,EAA6B,MAAM,WAAW,CAAC;AACvF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEtC,OAAO,EAAE,KAAK,wBAAwB,EAAyB,MAAM,WAAW,CAAC;AACjF,OAAO,EAAE,KAAK,WAAW,EAAuB,MAAM,YAAY,CAAC;AAEnE,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,0BAA0B,CAAC,SAAS,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,mBAAmB,CAAC;IAC3B,IAAI,EAAE,mBAAmB,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,UAAU,CAAC,EAAE,WAAW,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,iBAAiB,EAAE,0BAA0B,CAAC;IAC9C,QAAQ,EAAE,sBAAsB,CAAC;IACjC,OAAO,EAAE,wBAAwB,CAAC;CACnC;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,GAAG,QAAQ,CAE1E;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,mBAAmB,GAAG,wBAAwB,CAgC3F;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG;IAC3D,KAAK,EAAE,wBAAwB,CAAC;IAChC,IAAI,EAAE,wBAAwB,CAAC;CAChC,CAKA"}

package/dist/theme-colors.js

@@ -0,0 +1,44 @@
+import { generateHarmonyRoleColors } from './harmony';
+import { parseHexColorOrThrow } from './hex';
+import { generateNeutralSwatch } from './neutral';
+import { generateColorSwatch } from './swatches';
+export function getThemeModePrimaryHex(mode) {
+    return parseHexColorOrThrow(mode.primaryColor);
+}
+export function generateThemeModeColors(mode) {
+    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 = {
+        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) {
+    return {
+        light: generateThemeModeColors(theme.light),
+        dark: generateThemeModeColors(theme.dark),
+    };
+}
+//# sourceMappingURL=theme-colors.js.map

package/dist/theme-colors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-colors.js","sourceRoot":"","sources":["../src/theme-colors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAEvF,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAiC,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACjF,OAAO,EAAoB,mBAAmB,EAAE,MAAM,YAAY,CAAC;AA0BnE,MAAM,UAAU,sBAAsB,CAAC,IAAyB;IAC9D,OAAO,oBAAoB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,IAAyB;IAC/D,MAAM,UAAU,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,iBAAiB,GAAG,yBAAyB,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAE9E,MAAM,aAAa,GAAG,mBAAmB,CAAC,iBAAiB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;IAChF,MAAM,eAAe,GAAG,iBAAiB,CAAC,SAAS;QACjD,CAAC,CAAC,mBAAmB,CAAC,iBAAiB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,MAAM;QAC7D,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,cAAc,GAAG,iBAAiB,CAAC,QAAQ;QAC/C,CAAC,CAAC,mBAAmB,CAAC,iBAAiB,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM;QAC5D,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,gBAAgB,GAAG,iBAAiB,CAAC,UAAU;QACnD,CAAC,CAAC,mBAAmB,CAAC,iBAAiB,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM;QAC9D,CAAC,CAAC,SAAS,CAAC;IAEd,MAAM,OAAO,GAAG,qBAAqB,CAAC,iBAAiB,CAAC,CAAC;IACzD,MAAM,QAAQ,GAA2B;QACvC,OAAO,EAAE,aAAa;QACtB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9D,CAAC;IAEF,OAAO;QACL,iBAAiB;QACjB,QAAQ;QACR,OAAO,EAAE;YACP,eAAe,EAAE,OAAO,CAAC,eAAe;YACxC,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAsB;IAIxD,OAAO;QACL,KAAK,EAAE,uBAAuB,CAAC,KAAK,CAAC,KAAK,CAAC;QAC3C,IAAI,EAAE,uBAAuB,CAAC,KAAK,CAAC,IAAI,CAAC;KAC1C,CAAC;AACJ,CAAC","sourcesContent":["import { type GeneratedHarmonyRoleColors, generateHarmonyRoleColors } from './harmony';\nimport type { HexColor } from './hex';\nimport { parseHexColorOrThrow } from './hex';\nimport { type GeneratedNeutralMetadata, generateNeutralSwatch } from './neutral';\nimport { type ColorSwatch, generateColorSwatch } from './swatches';\n\nexport interface ThemeModeColorInput {\n  primaryColor: string;\n  harmony: GeneratedHarmonyRoleColors['harmony'];\n}\n\nexport interface ThemeColorInput {\n  light: ThemeModeColorInput;\n  dark: ThemeModeColorInput;\n}\n\nexport interface GeneratedThemeSwatches {\n  primary: ColorSwatch;\n  secondary?: ColorSwatch;\n  tertiary?: ColorSwatch;\n  quaternary?: ColorSwatch;\n  neutral: ColorSwatch;\n}\n\nexport interface GeneratedThemeModeColors {\n  harmonyRoleColors: GeneratedHarmonyRoleColors;\n  swatches: GeneratedThemeSwatches;\n  neutral: GeneratedNeutralMetadata;\n}\n\nexport function getThemeModePrimaryHex(mode: ThemeModeColorInput): HexColor {\n  return parseHexColorOrThrow(mode.primaryColor);\n}\n\nexport function generateThemeModeColors(mode: ThemeModeColorInput): GeneratedThemeModeColors {\n  const primaryHex = getThemeModePrimaryHex(mode);\n  const harmonyRoleColors = generateHarmonyRoleColors(primaryHex, mode.harmony);\n\n  const primarySwatch = generateColorSwatch(harmonyRoleColors.primary.hex).swatch;\n  const secondarySwatch = harmonyRoleColors.secondary\n    ? generateColorSwatch(harmonyRoleColors.secondary.hex).swatch\n    : undefined;\n  const tertiarySwatch = harmonyRoleColors.tertiary\n    ? generateColorSwatch(harmonyRoleColors.tertiary.hex).swatch\n    : undefined;\n  const quaternarySwatch = harmonyRoleColors.quaternary\n    ? generateColorSwatch(harmonyRoleColors.quaternary.hex).swatch\n    : undefined;\n\n  const neutral = generateNeutralSwatch(harmonyRoleColors);\n  const swatches: GeneratedThemeSwatches = {\n    primary: primarySwatch,\n    neutral: neutral.neutral,\n    ...(secondarySwatch ? { secondary: secondarySwatch } : {}),\n    ...(tertiarySwatch ? { tertiary: tertiarySwatch } : {}),\n    ...(quaternarySwatch ? { quaternary: quaternarySwatch } : {}),\n  };\n\n  return {\n    harmonyRoleColors,\n    swatches,\n    neutral: {\n      neutralKeyColor: neutral.neutralKeyColor,\n      diagnostics: neutral.diagnostics,\n    },\n  };\n}\n\nexport function generateThemeColors(theme: ThemeColorInput): {\n  light: GeneratedThemeModeColors;\n  dark: GeneratedThemeModeColors;\n} {\n  return {\n    light: generateThemeModeColors(theme.light),\n    dark: generateThemeModeColors(theme.dark),\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@ankhorage/color-theory",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "Standalone color theory, harmony, swatch, contrast, and theme color generation utilities.",
+  "homepage": "https://github.com/ankhorage/color-theory#readme",
+  "bugs": {
+    "url": "https://github.com/ankhorage/color-theory/issues"
+  },
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ankhorage/color-theory.git"
+  },
+  "keywords": [
+    "color",
+    "color-theory",
+    "culori",
+    "oklch",
+    "palette",
+    "swatches",
+    "theme"
+  ],
+  "dependencies": {
+    "culori": "^4.0.2"
+  },
+  "files": [
+    "dist",
+    "src",
+    "package.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "react-native": "./src/index.ts",
+      "browser": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./culori": {
+      "types": "./dist/culori.d.ts",
+      "import": "./dist/culori.js",
+      "default": "./dist/culori.js"
+    },
+    "./culori/fn": {
+      "types": "./dist/culori-fn.d.ts",
+      "import": "./dist/culori-fn.js",
+      "default": "./dist/culori-fn.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist tsconfig.tsbuildinfo && bun x tsc -p tsconfig.json",
+    "changeset": "changeset",
+    "changeset:status": "changeset status --since=origin/main",
+    "knip": "knip",
+    "lint": "eslint . --max-warnings=0",
+    "lint:fix": "eslint . --fix --max-warnings=0",
+    "format": "prettier --write .",
+    "paradox": "bunx @ankhorage/paradox",
+    "prepack": "bun run build",
+    "test": "bun test src",
+    "typecheck": "bun x tsc --noEmit -p tsconfig.json",
+    "version-packages": "changeset version"
+  },
+  "devDependencies": {
+    "@ankhorage/devtools": "^1.0.1",
+    "@ankhorage/paradox": "^0.0.3",
+    "@changesets/cli": "^2.31.0",
+    "@types/bun": "^1.3.13",
+    "@types/culori": "^4.0.1",
+    "@types/node": "^25.6.0",
+    "knip": "^5.88.1",
+    "typescript": "^5.9.3"
+  },
+  "packageManager": "bun@1.3.13"
+}

package/src/color-theory.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  COLOR_HARMONIES,
+  COLOR_SWATCH_BASE_STEP,
+  COLOR_SWATCH_STEPS,
+  generateColorSwatch,
+  generateHarmonyRoleColors,
+  generateNeutralSwatch,
+  generateThemeModeColors,
+  getReadableForeground,
+  parseHexColor,
+  parseHexColorOrThrow,
+} from './index';
+
+describe('color theory', () => {
+  it('parses valid hex colors and rejects invalid values', () => {
+    expect(parseHexColor('#3366ff')).toBe('#3366ff');
+    expect(parseHexColor('#3366FF')).toBe('#3366FF');
+    expect(parseHexColor('3366ff')).toBeNull();
+    expect(() => parseHexColorOrThrow('#12345')).toThrow();
+  });
+
+  it('generates harmony role colors with expected role counts', () => {
+    const primary = parseHexColorOrThrow('#3366ff');
+    const expectedRoleCount: Record<(typeof COLOR_HARMONIES)[number], number> = {
+      monochromatic: 1,
+      complementary: 2,
+      analogous: 3,
+      splitComplementary: 3,
+      triadic: 3,
+      tetradic: 4,
+    };
+
+    for (const harmony of COLOR_HARMONIES) {
+      const roleColors = generateHarmonyRoleColors(primary, harmony);
+      expect(roleColors.colors.length).toBe(expectedRoleCount[harmony]);
+      expect(roleColors.primary.hex).toBe(primary);
+      expect(roleColors.primary.source).toBe('selected');
+    }
+  });
+
+  it('generates 11-step swatches that preserve the base color at step 500', () => {
+    const base = parseHexColorOrThrow('#3366ff');
+    const { swatch, diagnostics } = generateColorSwatch(base);
+
+    expect(Object.keys(swatch).length).toBe(COLOR_SWATCH_STEPS.length);
+    expect(swatch[COLOR_SWATCH_BASE_STEP]).toBe(base);
+    expect(diagnostics.lightnessRange.max).toBeGreaterThanOrEqual(diagnostics.lightnessRange.min);
+  });
+
+  it('generates required neutral swatches from harmony role colors', () => {
+    const primary = parseHexColorOrThrow('#3366ff');
+    const roleColors = generateHarmonyRoleColors(primary, 'triadic');
+    const neutral = generateNeutralSwatch(roleColors);
+
+    expect(neutral.neutral[COLOR_SWATCH_BASE_STEP]).toBe(neutral.neutralKeyColor);
+    expect(neutral.diagnostics.lightnessRange.max).toBeGreaterThanOrEqual(
+      neutral.diagnostics.lightnessRange.min,
+    );
+  });
+
+  it('generates theme mode colors with one canonical swatch container', () => {
+    const generated = generateThemeModeColors({ primaryColor: '#3366ff', harmony: 'tetradic' });
+
+    expect(generated.harmonyRoleColors.primary.hex).toBe('#3366ff');
+    expect(generated.swatches.primary[COLOR_SWATCH_BASE_STEP]).toBe('#3366ff');
+    expect(generated.swatches.secondary?.[COLOR_SWATCH_BASE_STEP]).toBe(
+      generated.harmonyRoleColors.secondary?.hex,
+    );
+    expect(generated.swatches.tertiary?.[COLOR_SWATCH_BASE_STEP]).toBe(
+      generated.harmonyRoleColors.tertiary?.hex,
+    );
+    expect(generated.swatches.quaternary?.[COLOR_SWATCH_BASE_STEP]).toBe(
+      generated.harmonyRoleColors.quaternary?.hex,
+    );
+    expect(generated.swatches.neutral[COLOR_SWATCH_BASE_STEP]).toBe(
+      generated.neutral.neutralKeyColor,
+    );
+    expect(Object.hasOwn(generated, 'primary')).toBe(false);
+    expect(Object.hasOwn(generated, 'secondary')).toBe(false);
+  });
+
+  it('returns black or white readable foreground colors', () => {
+    const white = parseHexColorOrThrow('#FFFFFF');
+    const foreground = getReadableForeground(white);
+
+    expect(['#000000', '#FFFFFF']).toContain(foreground.foreground);
+    expect(foreground.contrast).toBeGreaterThan(0);
+  });
+});

package/src/contrast.ts

@@ -0,0 +1,22 @@
+import type { HexColor } from './hex';
+import { parseHexColorOrThrow } from './hex';
+import { contrastRatio } from './internal-culori';
+
+export interface ReadableForegroundResult {
+  foreground: HexColor;
+  contrast: number;
+}
+
+const BLACK = parseHexColorOrThrow('#000000');
+const WHITE = parseHexColorOrThrow('#FFFFFF');
+
+export function getReadableForeground(background: HexColor): ReadableForegroundResult {
+  const contrastOnBlack = contrastRatio(background, BLACK);
+  const contrastOnWhite = contrastRatio(background, WHITE);
+
+  if (contrastOnBlack >= contrastOnWhite) {
+    return { foreground: BLACK, contrast: contrastOnBlack };
+  }
+
+  return { foreground: WHITE, contrast: contrastOnWhite };
+}

package/src/culori-fn.ts

@@ -0,0 +1 @@
+export * from 'culori/fn';

package/src/culori.ts

@@ -0,0 +1 @@
+export * from 'culori';

package/src/harmony.ts

@@ -0,0 +1,92 @@
+import type { HexColor } from './hex';
+import { normalizeHueDegrees, oklchToHex, parseHexToOklch } from './internal-culori';
+
+export const COLOR_HARMONIES = [
+  'monochromatic',
+  'analogous',
+  'complementary',
+  'triadic',
+  'tetradic',
+  'splitComplementary',
+] as const;
+
+export type ColorHarmony = (typeof COLOR_HARMONIES)[number];
+
+export type GeneratedColorRole = 'primary' | 'secondary' | 'tertiary' | 'quaternary';
+
+export interface GeneratedHarmonyRoleColor {
+  role: GeneratedColorRole;
+  hex: HexColor;
+  hueDegrees: number;
+  source: 'selected' | 'generated';
+}
+
+export interface GeneratedHarmonyRoleColors {
+  harmony: ColorHarmony;
+  colors: readonly GeneratedHarmonyRoleColor[];
+  primary: GeneratedHarmonyRoleColor;
+  secondary?: GeneratedHarmonyRoleColor;
+  tertiary?: GeneratedHarmonyRoleColor;
+  quaternary?: GeneratedHarmonyRoleColor;
+}
+
+const ROLE_ORDER_BY_HARMONY: Record<ColorHarmony, readonly GeneratedColorRole[]> = {
+  monochromatic: ['primary'],
+  complementary: ['primary', 'secondary'],
+  analogous: ['primary', 'secondary', 'tertiary'],
+  splitComplementary: ['primary', 'secondary', 'tertiary'],
+  triadic: ['primary', 'secondary', 'tertiary'],
+  tetradic: ['primary', 'secondary', 'tertiary', 'quaternary'],
+};
+
+const OFFSETS_BY_HARMONY: Record<ColorHarmony, readonly number[]> = {
+  monochromatic: [0],
+  analogous: [0, -30, 30],
+  complementary: [0, 180],
+  splitComplementary: [0, 150, 210],
+  triadic: [0, 120, 240],
+  tetradic: [0, 90, 180, 270],
+};
+
+export function generateHarmonyRoleColors(
+  primaryColor: HexColor,
+  harmony: ColorHarmony,
+): GeneratedHarmonyRoleColors {
+  const base = parseHexToOklch(primaryColor);
+  const roles = ROLE_ORDER_BY_HARMONY[harmony];
+  const offsets = OFFSETS_BY_HARMONY[harmony];
+  const baseHue = normalizeHueDegrees(base.h);
+
+  const colors: GeneratedHarmonyRoleColor[] = [];
+
+  for (let index = 0; index < roles.length; index++) {
+    const role = roles[index];
+    if (!role) continue;
+
+    const hueDegrees = normalizeHueDegrees(baseHue + (offsets[index] ?? 0));
+    colors.push({
+      role,
+      hex: role === 'primary' ? primaryColor : oklchToHex({ ...base, h: hueDegrees }),
+      hueDegrees,
+      source: role === 'primary' ? 'selected' : 'generated',
+    });
+  }
+
+  const primary = colors.find((color) => color.role === 'primary');
+  if (!primary) {
+    throw new Error('[color-theory] Expected generated harmony role colors to include primary.');
+  }
+
+  const secondary = colors.find((color) => color.role === 'secondary');
+  const tertiary = colors.find((color) => color.role === 'tertiary');
+  const quaternary = colors.find((color) => color.role === 'quaternary');
+
+  return {
+    harmony,
+    colors,
+    primary,
+    ...(secondary ? { secondary } : {}),
+    ...(tertiary ? { tertiary } : {}),
+    ...(quaternary ? { quaternary } : {}),
+  };
+}

package/src/hex.ts

@@ -0,0 +1,29 @@
+export type HexColor = string & { readonly __hexColorBrand: unique symbol };
+
+const HEX6_CASE_INSENSITIVE_REGEX = /^#[0-9a-fA-F]{6}$/;
+
+export function isHexColor(value: string): value is HexColor {
+  return HEX6_CASE_INSENSITIVE_REGEX.test(value);
+}
+
+export function parseHexColor(value: string): HexColor | null {
+  if (!HEX6_CASE_INSENSITIVE_REGEX.test(value)) return null;
+  return value as HexColor;
+}
+
+export function parseHexColorOrThrow(value: string): HexColor {
+  const parsed = parseHexColor(value);
+  if (!parsed) {
+    throw new Error(`Invalid hex color (expected #RRGGBB or #rrggbb): ${JSON.stringify(value)}`);
+  }
+  return parsed;
+}
+
+export const normalizeHexColor = parseHexColor;
+export const normalizeHexColorOrThrow = parseHexColorOrThrow;
+
+export function assertHexColor(value: string): asserts value is HexColor {
+  if (!isHexColor(value)) {
+    throw new Error(`Invalid hex color (expected #RRGGBB or #rrggbb): ${JSON.stringify(value)}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './contrast';
+export * from './harmony';
+export * from './hex';
+export * from './neutral';
+export * from './semantics';
+export * from './swatches';
+export * from './theme-colors';

package/src/internal-culori.ts

@@ -0,0 +1,100 @@
+import {
+  converter,
+  differenceEuclidean,
+  formatHex,
+  toGamut,
+  wcagContrast,
+  wcagLuminance,
+} from 'culori';
+
+import type { HexColor } from './hex';
+import { parseHexColorOrThrow } from './hex';
+
+export interface OklchColor {
+  mode: 'oklch';
+  l: number;
+  c: number;
+  h: number;
+  alpha?: number;
+}
+
+export interface RgbColor {
+  mode: 'rgb';
+  r: number;
+  g: number;
+  b: number;
+  alpha?: number;
+}
+
+const toOklch = converter('oklch');
+const toRgb = converter('rgb');
+const toRgbGamut = toGamut('rgb', 'oklch');
+const deltaE = differenceEuclidean('oklch');
+
+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 normalizeHueDegrees(hueDegrees: number): number {
+  const hue = ((hueDegrees % 360) + 360) % 360;
+  return hue === 360 ? 0 : hue;
+}
+
+export function parseHexToOklch(hex: HexColor): OklchColor {
+  const color = toOklch(hex) as unknown as OklchColor | undefined;
+  if (color?.mode !== 'oklch') {
+    throw new Error(`Failed to convert hex to OKLCH: ${hex}`);
+  }
+
+  const l = clampNumber(color.l, 0, 1);
+  const c = clampNumber(color.c, 0, 0.4);
+  const h = normalizeHueDegrees(Number.isFinite(color.h) ? color.h : 0);
+
+  return { mode: 'oklch', l, c, h, alpha: color.alpha };
+}
+
+export function oklchToHex(oklch: OklchColor): HexColor {
+  const gamutRgb = toRgbGamut(oklch) as unknown as RgbColor | undefined;
+  const hex = formatHex(gamutRgb ?? oklch);
+  return parseHexColorOrThrow(hex);
+}
+
+export function toOklchColor(input: string | object): OklchColor {
+  const color = toOklch(input as never) as unknown as OklchColor | undefined;
+  if (color?.mode !== 'oklch') {
+    throw new Error(`Failed to parse/convert to OKLCH: ${JSON.stringify(input)}`);
+  }
+
+  const l = clampNumber(color.l, 0, 1);
+  const c = clampNumber(color.c, 0, 0.4);
+  const h = normalizeHueDegrees(Number.isFinite(color.h) ? color.h : 0);
+
+  return { mode: 'oklch', l, c, h, alpha: color.alpha };
+}
+
+export function toHexColor(input: string | object): HexColor {
+  const gamutRgb = toRgbGamut(input as never) as unknown as RgbColor | undefined;
+  const hex = formatHex(gamutRgb ?? (input as never));
+  return parseHexColorOrThrow(hex);
+}
+
+export function deltaEoklch(a: OklchColor, b: OklchColor): number {
+  return deltaE(a, b);
+}
+
+export function contrastRatio(colorA: string | object, colorB: string | object): number {
+  return wcagContrast(colorA as never, colorB as never);
+}
+
+export function relativeLuminance(color: string | object): number {
+  return wcagLuminance(color as never);
+}
+
+export function rgbFrom(input: string | object): RgbColor {
+  const rgb = toRgb(input as never) as unknown as RgbColor | undefined;
+  if (rgb?.mode !== 'rgb') {
+    throw new Error(`Failed to convert to rgb: ${JSON.stringify(input)}`);
+  }
+  return rgb;
+}