@ankhorage/color-theory 0.0.8 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @ankhorage/color-theory
 
+## 0.2.0
+
+### Minor Changes
+
+- 78cd2ca: Publish the canonical seven-harmony catalog, distinguish tetradic and square geometry, and report unreliable hue generation for achromatic or low-chroma primary colors.
+
+## 0.1.0
+
+### Minor Changes
+
+- be8317b: Add public contrast measurement, caller-defined foreground selection, and deterministic swatch-step selection with perceptual and contrast diagnostics.
+
 ## 0.0.8
 
 ### Patch Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/color-theory
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v0.0.7](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
+![license: MIT](././paradox/badges/license.svg) ![npm: v0.0.8](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
 
 Standalone color theory, harmony, swatch, contrast, and theme color generation utilities.
 
@@ -16,62 +16,12 @@ Standalone color theory, harmony, swatch, contrast, and theme color generation u
 - [Module relationships](././paradox/diagrams/module-relationships.mmd)
 - [Export graph](././paradox/diagrams/export-graph.mmd)
 - [assertHexColor sequence](././paradox/diagrams/sequences/assert-hex-color.mmd)
+- [createDefaultSemanticStatusSwatches sequence](././paradox/diagrams/sequences/create-default-semantic-status-swatches.mmd)
+- [createSemanticStatusSwatches sequence](././paradox/diagrams/sequences/create-semantic-status-swatches.mmd)
+- [generateColorSwatch sequence](././paradox/diagrams/sequences/generate-color-swatch.mmd)
+- [getContrastRatio sequence](././paradox/diagrams/sequences/get-contrast-ratio.mmd)
 - [getReadableForeground sequence](././paradox/diagrams/sequences/get-readable-foreground.mmd)
 - [getThemeModePrimaryHex sequence](././paradox/diagrams/sequences/get-theme-mode-primary-hex.mmd)
 - [parseHexColorOrThrow sequence](././paradox/diagrams/sequences/parse-hex-color-or-throw.mmd)
-
-## Architecture preview
-
-<details>
-<summary>Architecture overview</summary>
-
-```mermaid
-graph TD
-  package__ankhorage_color_theory["@ankhorage/color-theory"]
-  entrypoint_src_index_ts["src/index.ts"]
-  package__ankhorage_color_theory --> entrypoint_src_index_ts
-  module_src_contrast_ts["src/contrast.ts"]
-  package__ankhorage_color_theory -.-> module_src_contrast_ts
-  module_src_contrast_ts --> module_src_hex_ts
-  module_src_contrast_ts --> module_src_internal_culori_ts
-  module_src_culori_fn_ts["src/culori-fn.ts"]
-  package__ankhorage_color_theory -.-> module_src_culori_fn_ts
-  module_src_culori_ts["src/culori.ts"]
-  package__ankhorage_color_theory -.-> module_src_culori_ts
-  module_src_harmony_ts["src/harmony.ts"]
-  package__ankhorage_color_theory -.-> module_src_harmony_ts
-  module_src_harmony_ts --> module_src_hex_ts
-  module_src_harmony_ts --> module_src_internal_culori_ts
-  module_src_hex_ts["src/hex.ts"]
-  package__ankhorage_color_theory -.-> module_src_hex_ts
-  module_src_index_ts["src/index.ts"]
-  module_src_internal_culori_ts["src/internal-culori.ts"]
-  package__ankhorage_color_theory -.-> module_src_internal_culori_ts
-  module_src_internal_culori_ts --> module_src_hex_ts
-  module_src_neutral_ts["src/neutral.ts"]
-  package__ankhorage_color_theory -.-> module_src_neutral_ts
-  module_src_neutral_ts --> module_src_harmony_ts
-  module_src_neutral_ts --> module_src_hex_ts
-  module_src_neutral_ts --> module_src_internal_culori_ts
-  module_src_neutral_ts --> module_src_swatches_ts
-  module_src_semantic_status_ts["src/semantic-status.ts"]
-  package__ankhorage_color_theory -.-> module_src_semantic_status_ts
-  module_src_semantic_status_ts --> module_src_hex_ts
-  module_src_semantic_status_ts --> module_src_swatches_ts
-  module_src_semantics_ts["src/semantics.ts"]
-  package__ankhorage_color_theory -.-> module_src_semantics_ts
-  module_src_semantics_ts --> module_src_harmony_ts
-  module_src_semantics_ts --> module_src_swatches_ts
-  module_src_swatches_ts["src/swatches.ts"]
-  package__ankhorage_color_theory -.-> module_src_swatches_ts
-  module_src_swatches_ts --> module_src_hex_ts
-  module_src_swatches_ts --> module_src_internal_culori_ts
-  module_src_theme_colors_ts["src/theme-colors.ts"]
-  package__ankhorage_color_theory -.-> module_src_theme_colors_ts
-  module_src_theme_colors_ts --> module_src_harmony_ts
-  module_src_theme_colors_ts --> module_src_hex_ts
-  module_src_theme_colors_ts --> module_src_neutral_ts
-  module_src_theme_colors_ts --> module_src_swatches_ts
-```
-
-</details>
+- [selectColorSwatchStep sequence](././paradox/diagrams/sequences/select-color-swatch-step.mmd)
+- [selectReadableForeground sequence](././paradox/diagrams/sequences/select-readable-foreground.mmd)

package/dist/contrast.d.ts

@@ -3,6 +3,31 @@ export interface ReadableForegroundResult {
     foreground: HexColor;
     contrast: number;
 }
+export type ForegroundTiePolicy = 'first' | 'last';
+export interface ForegroundSelectionCandidate {
+    foreground: HexColor;
+    contrast: number;
+    passesMinimum: boolean;
+    selected: boolean;
+    rejectionReason?: 'minimum-contrast' | 'weaker-contrast' | 'tie-break';
+}
+export interface ForegroundSelectionResult {
+    selected: ForegroundSelectionCandidate | null;
+    candidates: readonly ForegroundSelectionCandidate[];
+    minimumContrast: number;
+    tieBreak: {
+        policy: ForegroundTiePolicy;
+        applied: boolean;
+    };
+}
+/***
+  Measure the WCAG contrast ratio between two validated hex colors.
+*/
+export declare function getContrastRatio(colorA: HexColor, colorB: HexColor): number;
+/***
+  Select the strongest caller-provided foreground that meets a minimum WCAG contrast ratio.
+*/
+export declare function selectReadableForeground(background: HexColor, foregrounds: readonly HexColor[], minimumContrast: number, tiePolicy: ForegroundTiePolicy): ForegroundSelectionResult;
 /***
   Return the readable black or white foreground color with the stronger contrast against a background color.
 */

package/dist/contrast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contrast.d.ts","sourceRoot":"","sources":["../src/contrast.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAItC,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,QAAQ,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAKD;;EAEE;AACF,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,QAAQ,GAAG,wBAAwB,CASpF"}
+{"version":3,"file":"contrast.d.ts","sourceRoot":"","sources":["../src/contrast.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAItC,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,QAAQ,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEnD,MAAM,WAAW,4BAA4B;IAC3C,UAAU,EAAE,QAAQ,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE,kBAAkB,GAAG,iBAAiB,GAAG,WAAW,CAAC;CACxE;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,4BAA4B,GAAG,IAAI,CAAC;IAC9C,UAAU,EAAE,SAAS,4BAA4B,EAAE,CAAC;IACpD,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,mBAAmB,CAAC;QAC5B,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC;CACH;AAKD;;EAEE;AACF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,GAAG,MAAM,CAE3E;AAED;;EAEE;AACF,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,QAAQ,EACpB,WAAW,EAAE,SAAS,QAAQ,EAAE,EAChC,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,mBAAmB,GAC7B,yBAAyB,CA8C3B;AAED;;EAEE;AACF,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,QAAQ,GAAG,wBAAwB,CAUpF"}

package/dist/contrast.js

@@ -2,15 +2,84 @@ import { parseHexColorOrThrow } from './hex';
 import { contrastRatio } from './internal-culori';
 const BLACK = parseHexColorOrThrow('#000000');
 const WHITE = parseHexColorOrThrow('#FFFFFF');
+/***
+  Measure the WCAG contrast ratio between two validated hex colors.
+*/
+export function getContrastRatio(colorA, colorB) {
+    return contrastRatio(colorA, colorB);
+}
+/***
+  Select the strongest caller-provided foreground that meets a minimum WCAG contrast ratio.
+*/
+export function selectReadableForeground(background, foregrounds, minimumContrast, tiePolicy) {
+    assertMinimumContrast(minimumContrast);
+    if (foregrounds.length === 0) {
+        throw new Error('[color-theory] Foreground candidates must not be empty.');
+    }
+    const normalizedBackground = parseHexColorOrThrow(background);
+    const measured = foregrounds.map((foreground, index) => {
+        const normalizedForeground = parseHexColorOrThrow(foreground);
+        return {
+            foreground: normalizedForeground,
+            contrast: getContrastRatio(normalizedBackground, normalizedForeground),
+            index,
+        };
+    });
+    const passing = measured.filter(({ contrast }) => contrast >= minimumContrast);
+    const strongestContrast = Math.max(...passing.map(({ contrast }) => contrast));
+    const strongest = passing.filter(({ contrast }) => contrast === strongestContrast);
+    const selectedMeasured = tiePolicy === 'first' ? strongest.at(0) : strongest.at(-1);
+    const tieBreakApplied = strongest.length > 1;
+    const candidates = measured.map(({ foreground, contrast, index }) => {
+        const selected = selectedMeasured?.index === index;
+        return {
+            foreground,
+            contrast,
+            passesMinimum: contrast >= minimumContrast,
+            selected,
+            ...(!selected
+                ? {
+                    rejectionReason: getForegroundRejectionReason(contrast, minimumContrast, strongestContrast),
+                }
+                : {}),
+        };
+    });
+    return {
+        selected: candidates.find(({ selected }) => selected) ?? null,
+        candidates,
+        minimumContrast,
+        tieBreak: { policy: tiePolicy, applied: tieBreakApplied },
+    };
+}
 /***
   Return the readable black or white foreground color with the stronger contrast against a background color.
 */
 export function getReadableForeground(background) {
-    const contrastOnBlack = contrastRatio(background, BLACK);
-    const contrastOnWhite = contrastRatio(background, WHITE);
-    if (contrastOnBlack >= contrastOnWhite) {
-        return { foreground: BLACK, contrast: contrastOnBlack };
+    const result = selectReadableForeground(background, [BLACK, WHITE], 1, 'first');
+    if (!result.selected) {
+        throw new Error('[color-theory] Expected black or white to be a readable foreground.');
     }
-    return { foreground: WHITE, contrast: contrastOnWhite };
+    return {
+        foreground: result.selected.foreground,
+        contrast: result.selected.contrast,
+    };
+}
+/***
+  Validate a WCAG contrast threshold.
+*/
+function assertMinimumContrast(minimumContrast) {
+    if (!Number.isFinite(minimumContrast) || minimumContrast < 1 || minimumContrast > 21) {
+        throw new Error(`[color-theory] Minimum contrast must be a finite ratio from 1 through 21: ${minimumContrast}.`);
+    }
+}
+/***
+  Explain why a foreground candidate was not selected.
+*/
+function getForegroundRejectionReason(contrast, minimumContrast, strongestContrast) {
+    if (contrast < minimumContrast)
+        return 'minimum-contrast';
+    if (contrast < strongestContrast)
+        return 'weaker-contrast';
+    return 'tie-break';
 }
 //# sourceMappingURL=contrast.js.map

package/dist/contrast.js.map

@@ -1 +1 @@
-{"version":3,"file":"contrast.js","sourceRoot":"","sources":["../src/contrast.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOlD,MAAM,KAAK,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;AAC9C,MAAM,KAAK,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;AAE9C;;EAEE;AACF,MAAM,UAAU,qBAAqB,CAAC,UAAoB;IACxD,MAAM,eAAe,GAAG,aAAa,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACzD,MAAM,eAAe,GAAG,aAAa,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAEzD,IAAI,eAAe,IAAI,eAAe,EAAE,CAAC;QACvC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC1D,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;AAC1D,CAAC","sourcesContent":["import type { HexColor } from './hex';\nimport { parseHexColorOrThrow } from './hex';\nimport { contrastRatio } from './internal-culori';\n\nexport interface ReadableForegroundResult {\n  foreground: HexColor;\n  contrast: number;\n}\n\nconst BLACK = parseHexColorOrThrow('#000000');\nconst WHITE = parseHexColorOrThrow('#FFFFFF');\n\n/***\n  Return the readable black or white foreground color with the stronger contrast against a background color.\n*/\nexport function getReadableForeground(background: HexColor): ReadableForegroundResult {\n  const contrastOnBlack = contrastRatio(background, BLACK);\n  const contrastOnWhite = contrastRatio(background, WHITE);\n\n  if (contrastOnBlack >= contrastOnWhite) {\n    return { foreground: BLACK, contrast: contrastOnBlack };\n  }\n\n  return { foreground: WHITE, contrast: contrastOnWhite };\n}\n"]}
+{"version":3,"file":"contrast.js","sourceRoot":"","sources":["../src/contrast.ts"],"names":[],"mappings":"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","sourcesContent":["import type { HexColor } from './hex';\nimport { parseHexColorOrThrow } from './hex';\nimport { contrastRatio } from './internal-culori';\n\nexport interface ReadableForegroundResult {\n  foreground: HexColor;\n  contrast: number;\n}\n\nexport type ForegroundTiePolicy = 'first' | 'last';\n\nexport interface ForegroundSelectionCandidate {\n  foreground: HexColor;\n  contrast: number;\n  passesMinimum: boolean;\n  selected: boolean;\n  rejectionReason?: 'minimum-contrast' | 'weaker-contrast' | 'tie-break';\n}\n\nexport interface ForegroundSelectionResult {\n  selected: ForegroundSelectionCandidate | null;\n  candidates: readonly ForegroundSelectionCandidate[];\n  minimumContrast: number;\n  tieBreak: {\n    policy: ForegroundTiePolicy;\n    applied: boolean;\n  };\n}\n\nconst BLACK = parseHexColorOrThrow('#000000');\nconst WHITE = parseHexColorOrThrow('#FFFFFF');\n\n/***\n  Measure the WCAG contrast ratio between two validated hex colors.\n*/\nexport function getContrastRatio(colorA: HexColor, colorB: HexColor): number {\n  return contrastRatio(colorA, colorB);\n}\n\n/***\n  Select the strongest caller-provided foreground that meets a minimum WCAG contrast ratio.\n*/\nexport function selectReadableForeground(\n  background: HexColor,\n  foregrounds: readonly HexColor[],\n  minimumContrast: number,\n  tiePolicy: ForegroundTiePolicy,\n): ForegroundSelectionResult {\n  assertMinimumContrast(minimumContrast);\n  if (foregrounds.length === 0) {\n    throw new Error('[color-theory] Foreground candidates must not be empty.');\n  }\n\n  const normalizedBackground = parseHexColorOrThrow(background);\n  const measured = foregrounds.map((foreground, index) => {\n    const normalizedForeground = parseHexColorOrThrow(foreground);\n    return {\n      foreground: normalizedForeground,\n      contrast: getContrastRatio(normalizedBackground, normalizedForeground),\n      index,\n    };\n  });\n  const passing = measured.filter(({ contrast }) => contrast >= minimumContrast);\n  const strongestContrast = Math.max(...passing.map(({ contrast }) => contrast));\n  const strongest = passing.filter(({ contrast }) => contrast === strongestContrast);\n  const selectedMeasured = tiePolicy === 'first' ? strongest.at(0) : strongest.at(-1);\n  const tieBreakApplied = strongest.length > 1;\n\n  const candidates = measured.map(({ foreground, contrast, index }) => {\n    const selected = selectedMeasured?.index === index;\n    return {\n      foreground,\n      contrast,\n      passesMinimum: contrast >= minimumContrast,\n      selected,\n      ...(!selected\n        ? {\n            rejectionReason: getForegroundRejectionReason(\n              contrast,\n              minimumContrast,\n              strongestContrast,\n            ),\n          }\n        : {}),\n    } satisfies ForegroundSelectionCandidate;\n  });\n\n  return {\n    selected: candidates.find(({ selected }) => selected) ?? null,\n    candidates,\n    minimumContrast,\n    tieBreak: { policy: tiePolicy, applied: tieBreakApplied },\n  };\n}\n\n/***\n  Return the readable black or white foreground color with the stronger contrast against a background color.\n*/\nexport function getReadableForeground(background: HexColor): ReadableForegroundResult {\n  const result = selectReadableForeground(background, [BLACK, WHITE], 1, 'first');\n  if (!result.selected) {\n    throw new Error('[color-theory] Expected black or white to be a readable foreground.');\n  }\n\n  return {\n    foreground: result.selected.foreground,\n    contrast: result.selected.contrast,\n  };\n}\n\n/***\n  Validate a WCAG contrast threshold.\n*/\nfunction assertMinimumContrast(minimumContrast: number): void {\n  if (!Number.isFinite(minimumContrast) || minimumContrast < 1 || minimumContrast > 21) {\n    throw new Error(\n      `[color-theory] Minimum contrast must be a finite ratio from 1 through 21: ${minimumContrast}.`,\n    );\n  }\n}\n\n/***\n  Explain why a foreground candidate was not selected.\n*/\nfunction getForegroundRejectionReason(\n  contrast: number,\n  minimumContrast: number,\n  strongestContrast: number,\n): NonNullable<ForegroundSelectionCandidate['rejectionReason']> {\n  if (contrast < minimumContrast) return 'minimum-contrast';\n  if (contrast < strongestContrast) return 'weaker-contrast';\n  return 'tie-break';\n}\n"]}

package/dist/harmony.d.ts

@@ -1,7 +1,69 @@
 import type { HexColor } from './hex';
-export declare const COLOR_HARMONIES: readonly ["monochromatic", "analogous", "complementary", "triadic", "tetradic", "splitComplementary"];
-export type ColorHarmony = (typeof COLOR_HARMONIES)[number];
 export type GeneratedColorRole = 'primary' | 'secondary' | 'tertiary' | 'quaternary';
+export declare const COLOR_HARMONY_CATALOG: readonly [{
+    readonly id: "monochromatic";
+    readonly label: "Monochromatic";
+    readonly description: "Uses one hue with ramp variation.";
+    readonly offsets: readonly [0];
+    readonly roles: readonly ["primary"];
+    readonly roleCount: 1;
+}, {
+    readonly id: "analogous";
+    readonly label: "Analogous";
+    readonly description: "Uses the primary hue and its two neighboring hues at minus and plus 30 degrees.";
+    readonly offsets: readonly [0, -30, 30];
+    readonly roles: readonly ["primary", "secondary", "tertiary"];
+    readonly roleCount: 3;
+}, {
+    readonly id: "complementary";
+    readonly label: "Complementary";
+    readonly description: "Pairs the primary hue with its opposite hue at 180 degrees.";
+    readonly offsets: readonly [0, 180];
+    readonly roles: readonly ["primary", "secondary"];
+    readonly roleCount: 2;
+}, {
+    readonly id: "splitComplementary";
+    readonly label: "Split complementary";
+    readonly description: "Uses the primary hue with hues at 150 and 210 degrees.";
+    readonly offsets: readonly [0, 150, 210];
+    readonly roles: readonly ["primary", "secondary", "tertiary"];
+    readonly roleCount: 3;
+}, {
+    readonly id: "triadic";
+    readonly label: "Triadic";
+    readonly description: "Uses three evenly spaced hues at 120-degree intervals.";
+    readonly offsets: readonly [0, 120, 240];
+    readonly roles: readonly ["primary", "secondary", "tertiary"];
+    readonly roleCount: 3;
+}, {
+    readonly id: "tetradic";
+    readonly label: "Tetradic";
+    readonly description: "Uses a rectangular tetrad at 0, 60, 180, and 240 degrees.";
+    readonly offsets: readonly [0, 60, 180, 240];
+    readonly roles: readonly ["primary", "secondary", "tertiary", "quaternary"];
+    readonly roleCount: 4;
+}, {
+    readonly id: "square";
+    readonly label: "Square";
+    readonly description: "Uses four evenly spaced hues at 90-degree intervals.";
+    readonly offsets: readonly [0, 90, 180, 270];
+    readonly roles: readonly ["primary", "secondary", "tertiary", "quaternary"];
+    readonly roleCount: 4;
+}];
+export type ColorHarmonyDefinition = (typeof COLOR_HARMONY_CATALOG)[number];
+export type ColorHarmony = ColorHarmonyDefinition['id'];
+export declare const COLOR_HARMONIES: readonly ColorHarmony[];
+export declare const MIN_HUEFUL_CHROMA = 0.015;
+export type HarmonyGenerationWarningCode = 'achromatic_primary' | 'low_chroma_primary';
+export interface HarmonyGenerationWarning {
+    readonly code: HarmonyGenerationWarningCode;
+    readonly message: string;
+}
+export interface HarmonyGenerationDiagnostics {
+    readonly isHueReliable: boolean;
+    readonly primaryChroma: number;
+    readonly warnings: readonly HarmonyGenerationWarning[];
+}
 export interface GeneratedHarmonyRoleColor {
     role: GeneratedColorRole;
     hex: HexColor;
@@ -15,6 +77,7 @@ export interface GeneratedHarmonyRoleColors {
     secondary?: GeneratedHarmonyRoleColor;
     tertiary?: GeneratedHarmonyRoleColor;
     quaternary?: GeneratedHarmonyRoleColor;
+    diagnostics: HarmonyGenerationDiagnostics;
 }
 /***
   Generate role-based harmony colors from a primary color and harmony strategy.

package/dist/harmony.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"harmony.d.ts","sourceRoot":"","sources":["../src/harmony.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGtC,eAAO,MAAM,eAAe,uGAOlB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,YAAY,CAAC;AAErF,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,kBAAkB,CAAC;IACzB,GAAG,EAAE,QAAQ,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,UAAU,GAAG,WAAW,CAAC;CAClC;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC7C,OAAO,EAAE,yBAAyB,CAAC;IACnC,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC,QAAQ,CAAC,EAAE,yBAAyB,CAAC;IACrC,UAAU,CAAC,EAAE,yBAAyB,CAAC;CACxC;AAoBD;;EAEE;AACF,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,QAAQ,EACtB,OAAO,EAAE,YAAY,GACpB,0BAA0B,CAsC5B"}
+{"version":3,"file":"harmony.d.ts","sourceRoot":"","sources":["../src/harmony.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGtC,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,YAAY,CAAC;AAWrF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyDsB,CAAC;AAEzD,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC5E,MAAM,MAAM,YAAY,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;AAExD,eAAO,MAAM,eAAe,EAAE,SAAS,YAAY,EAA8C,CAAC;AAElG,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,GAAG,oBAAoB,CAAC;AAEvF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACxD;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,kBAAkB,CAAC;IACzB,GAAG,EAAE,QAAQ,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,UAAU,GAAG,WAAW,CAAC;CAClC;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC7C,OAAO,EAAE,yBAAyB,CAAC;IACnC,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC,QAAQ,CAAC,EAAE,yBAAyB,CAAC;IACrC,UAAU,CAAC,EAAE,yBAAyB,CAAC;IACvC,WAAW,EAAE,4BAA4B,CAAC;CAC3C;AAqCD;;EAEE;AACF,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,QAAQ,EACtB,OAAO,EAAE,YAAY,GACpB,0BAA0B,CAiC5B"}

package/dist/harmony.js

@@ -1,49 +1,113 @@
 import { normalizeHueDegrees, oklchToHex, parseHexToOklch } from './internal-culori';
-export const COLOR_HARMONIES = [
-    'monochromatic',
-    'analogous',
-    'complementary',
-    'triadic',
-    'tetradic',
-    'splitComplementary',
+export const COLOR_HARMONY_CATALOG = [
+    {
+        id: 'monochromatic',
+        label: 'Monochromatic',
+        description: 'Uses one hue with ramp variation.',
+        offsets: [0],
+        roles: ['primary'],
+        roleCount: 1,
+    },
+    {
+        id: 'analogous',
+        label: 'Analogous',
+        description: 'Uses the primary hue and its two neighboring hues at minus and plus 30 degrees.',
+        offsets: [0, -30, 30],
+        roles: ['primary', 'secondary', 'tertiary'],
+        roleCount: 3,
+    },
+    {
+        id: 'complementary',
+        label: 'Complementary',
+        description: 'Pairs the primary hue with its opposite hue at 180 degrees.',
+        offsets: [0, 180],
+        roles: ['primary', 'secondary'],
+        roleCount: 2,
+    },
+    {
+        id: 'splitComplementary',
+        label: 'Split complementary',
+        description: 'Uses the primary hue with hues at 150 and 210 degrees.',
+        offsets: [0, 150, 210],
+        roles: ['primary', 'secondary', 'tertiary'],
+        roleCount: 3,
+    },
+    {
+        id: 'triadic',
+        label: 'Triadic',
+        description: 'Uses three evenly spaced hues at 120-degree intervals.',
+        offsets: [0, 120, 240],
+        roles: ['primary', 'secondary', 'tertiary'],
+        roleCount: 3,
+    },
+    {
+        id: 'tetradic',
+        label: 'Tetradic',
+        description: 'Uses a rectangular tetrad at 0, 60, 180, and 240 degrees.',
+        offsets: [0, 60, 180, 240],
+        roles: ['primary', 'secondary', 'tertiary', 'quaternary'],
+        roleCount: 4,
+    },
+    {
+        id: 'square',
+        label: 'Square',
+        description: 'Uses four evenly spaced hues at 90-degree intervals.',
+        offsets: [0, 90, 180, 270],
+        roles: ['primary', 'secondary', 'tertiary', 'quaternary'],
+        roleCount: 4,
+    },
 ];
-const ROLE_ORDER_BY_HARMONY = {
-    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 = {
-    monochromatic: [0],
-    analogous: [0, -30, 30],
-    complementary: [0, 180],
-    splitComplementary: [0, 150, 210],
-    triadic: [0, 120, 240],
-    tetradic: [0, 90, 180, 270],
-};
+export const COLOR_HARMONIES = COLOR_HARMONY_CATALOG.map(({ id }) => id);
+export const MIN_HUEFUL_CHROMA = 0.015;
+/***
+  Create diagnostics for the reliability of generated hue relationships.
+*/
+function createHarmonyGenerationDiagnostics(primaryChroma) {
+    const warnings = [];
+    if (primaryChroma === 0) {
+        warnings.push({
+            code: 'achromatic_primary',
+            message: 'The selected primary is achromatic, so generated hue relationships are not visible.',
+        });
+    }
+    else if (primaryChroma < MIN_HUEFUL_CHROMA) {
+        warnings.push({
+            code: 'low_chroma_primary',
+            message: 'The selected primary has low chroma, so generated hue relationships may be weak.',
+        });
+    }
+    return {
+        isHueReliable: primaryChroma >= MIN_HUEFUL_CHROMA,
+        primaryChroma,
+        warnings,
+    };
+}
+/***
+  Resolve a complete harmony definition from the canonical public catalog.
+*/
+function getHarmonyDefinition(harmony) {
+    const definition = COLOR_HARMONY_CATALOG.find(({ id }) => id === harmony);
+    if (!definition) {
+        throw new Error(`[color-theory] Missing definition for harmony ${harmony}.`);
+    }
+    return definition;
+}
 /***
   Generate role-based harmony colors from a primary color and harmony strategy.
 */
 export function generateHarmonyRoleColors(primaryColor, harmony) {
     const base = parseHexToOklch(primaryColor);
-    const roles = ROLE_ORDER_BY_HARMONY[harmony];
-    const offsets = OFFSETS_BY_HARMONY[harmony];
+    const definition = getHarmonyDefinition(harmony);
     const baseHue = normalizeHueDegrees(base.h);
-    const colors = [];
-    for (let index = 0; index < roles.length; index++) {
-        const role = roles[index];
-        if (!role)
-            continue;
-        const hueDegrees = normalizeHueDegrees(baseHue + (offsets[index] ?? 0));
-        colors.push({
+    const colors = definition.roles.map((role, index) => {
+        const hueDegrees = normalizeHueDegrees(baseHue + (definition.offsets.at(index) ?? 0));
+        return {
             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.');
@@ -58,6 +122,7 @@ export function generateHarmonyRoleColors(primaryColor, harmony) {
         ...(secondary ? { secondary } : {}),
         ...(tertiary ? { tertiary } : {}),
         ...(quaternary ? { quaternary } : {}),
+        diagnostics: createHarmonyGenerationDiagnostics(base.c),
     };
 }
 //# sourceMappingURL=harmony.js.map

package/dist/harmony.js.map

@@ -1 +1 @@
-{"version":3,"file":"harmony.js","sourceRoot":"","sources":["../src/harmony.ts"],"names":[],"mappings":"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","sourcesContent":["import type { HexColor } from './hex';\nimport { normalizeHueDegrees, oklchToHex, parseHexToOklch } from './internal-culori';\n\nexport const COLOR_HARMONIES = [\n  'monochromatic',\n  'analogous',\n  'complementary',\n  'triadic',\n  'tetradic',\n  'splitComplementary',\n] as const;\n\nexport type ColorHarmony = (typeof COLOR_HARMONIES)[number];\n\nexport type GeneratedColorRole = 'primary' | 'secondary' | 'tertiary' | 'quaternary';\n\nexport interface GeneratedHarmonyRoleColor {\n  role: GeneratedColorRole;\n  hex: HexColor;\n  hueDegrees: number;\n  source: 'selected' | 'generated';\n}\n\nexport interface GeneratedHarmonyRoleColors {\n  harmony: ColorHarmony;\n  colors: readonly GeneratedHarmonyRoleColor[];\n  primary: GeneratedHarmonyRoleColor;\n  secondary?: GeneratedHarmonyRoleColor;\n  tertiary?: GeneratedHarmonyRoleColor;\n  quaternary?: GeneratedHarmonyRoleColor;\n}\n\nconst ROLE_ORDER_BY_HARMONY: Record<ColorHarmony, readonly GeneratedColorRole[]> = {\n  monochromatic: ['primary'],\n  complementary: ['primary', 'secondary'],\n  analogous: ['primary', 'secondary', 'tertiary'],\n  splitComplementary: ['primary', 'secondary', 'tertiary'],\n  triadic: ['primary', 'secondary', 'tertiary'],\n  tetradic: ['primary', 'secondary', 'tertiary', 'quaternary'],\n};\n\nconst OFFSETS_BY_HARMONY: Record<ColorHarmony, readonly number[]> = {\n  monochromatic: [0],\n  analogous: [0, -30, 30],\n  complementary: [0, 180],\n  splitComplementary: [0, 150, 210],\n  triadic: [0, 120, 240],\n  tetradic: [0, 90, 180, 270],\n};\n\n/***\n  Generate role-based harmony colors from a primary color and harmony strategy.\n*/\nexport function generateHarmonyRoleColors(\n  primaryColor: HexColor,\n  harmony: ColorHarmony,\n): GeneratedHarmonyRoleColors {\n  const base = parseHexToOklch(primaryColor);\n  const roles = ROLE_ORDER_BY_HARMONY[harmony];\n  const offsets = OFFSETS_BY_HARMONY[harmony];\n  const baseHue = normalizeHueDegrees(base.h);\n\n  const colors: GeneratedHarmonyRoleColor[] = [];\n\n  for (let index = 0; index < roles.length; index++) {\n    const role = roles[index];\n    if (!role) continue;\n\n    const hueDegrees = normalizeHueDegrees(baseHue + (offsets[index] ?? 0));\n    colors.push({\n      role,\n      hex: role === 'primary' ? primaryColor : oklchToHex({ ...base, h: hueDegrees }),\n      hueDegrees,\n      source: role === 'primary' ? 'selected' : 'generated',\n    });\n  }\n\n  const primary = colors.find((color) => color.role === 'primary');\n  if (!primary) {\n    throw new Error('[color-theory] Expected generated harmony role colors to include primary.');\n  }\n\n  const secondary = colors.find((color) => color.role === 'secondary');\n  const tertiary = colors.find((color) => color.role === 'tertiary');\n  const quaternary = colors.find((color) => color.role === 'quaternary');\n\n  return {\n    harmony,\n    colors,\n    primary,\n    ...(secondary ? { secondary } : {}),\n    ...(tertiary ? { tertiary } : {}),\n    ...(quaternary ? { quaternary } : {}),\n  };\n}\n"]}
+{"version":3,"file":"harmony.js","sourceRoot":"","sources":["../src/harmony.ts"],"names":[],"mappings":"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","sourcesContent":["import type { HexColor } from './hex';\nimport { normalizeHueDegrees, oklchToHex, parseHexToOklch } from './internal-culori';\n\nexport type GeneratedColorRole = 'primary' | 'secondary' | 'tertiary' | 'quaternary';\n\ninterface ColorHarmonyCatalogEntry {\n  readonly id: string;\n  readonly label: string;\n  readonly description: string;\n  readonly offsets: readonly number[];\n  readonly roles: readonly GeneratedColorRole[];\n  readonly roleCount: 1 | 2 | 3 | 4;\n}\n\nexport const COLOR_HARMONY_CATALOG = [\n  {\n    id: 'monochromatic',\n    label: 'Monochromatic',\n    description: 'Uses one hue with ramp variation.',\n    offsets: [0],\n    roles: ['primary'],\n    roleCount: 1,\n  },\n  {\n    id: 'analogous',\n    label: 'Analogous',\n    description: 'Uses the primary hue and its two neighboring hues at minus and plus 30 degrees.',\n    offsets: [0, -30, 30],\n    roles: ['primary', 'secondary', 'tertiary'],\n    roleCount: 3,\n  },\n  {\n    id: 'complementary',\n    label: 'Complementary',\n    description: 'Pairs the primary hue with its opposite hue at 180 degrees.',\n    offsets: [0, 180],\n    roles: ['primary', 'secondary'],\n    roleCount: 2,\n  },\n  {\n    id: 'splitComplementary',\n    label: 'Split complementary',\n    description: 'Uses the primary hue with hues at 150 and 210 degrees.',\n    offsets: [0, 150, 210],\n    roles: ['primary', 'secondary', 'tertiary'],\n    roleCount: 3,\n  },\n  {\n    id: 'triadic',\n    label: 'Triadic',\n    description: 'Uses three evenly spaced hues at 120-degree intervals.',\n    offsets: [0, 120, 240],\n    roles: ['primary', 'secondary', 'tertiary'],\n    roleCount: 3,\n  },\n  {\n    id: 'tetradic',\n    label: 'Tetradic',\n    description: 'Uses a rectangular tetrad at 0, 60, 180, and 240 degrees.',\n    offsets: [0, 60, 180, 240],\n    roles: ['primary', 'secondary', 'tertiary', 'quaternary'],\n    roleCount: 4,\n  },\n  {\n    id: 'square',\n    label: 'Square',\n    description: 'Uses four evenly spaced hues at 90-degree intervals.',\n    offsets: [0, 90, 180, 270],\n    roles: ['primary', 'secondary', 'tertiary', 'quaternary'],\n    roleCount: 4,\n  },\n] as const satisfies readonly ColorHarmonyCatalogEntry[];\n\nexport type ColorHarmonyDefinition = (typeof COLOR_HARMONY_CATALOG)[number];\nexport type ColorHarmony = ColorHarmonyDefinition['id'];\n\nexport const COLOR_HARMONIES: readonly ColorHarmony[] = COLOR_HARMONY_CATALOG.map(({ id }) => id);\n\nexport const MIN_HUEFUL_CHROMA = 0.015;\n\nexport type HarmonyGenerationWarningCode = 'achromatic_primary' | 'low_chroma_primary';\n\nexport interface HarmonyGenerationWarning {\n  readonly code: HarmonyGenerationWarningCode;\n  readonly message: string;\n}\n\nexport interface HarmonyGenerationDiagnostics {\n  readonly isHueReliable: boolean;\n  readonly primaryChroma: number;\n  readonly warnings: readonly HarmonyGenerationWarning[];\n}\n\nexport interface GeneratedHarmonyRoleColor {\n  role: GeneratedColorRole;\n  hex: HexColor;\n  hueDegrees: number;\n  source: 'selected' | 'generated';\n}\n\nexport interface GeneratedHarmonyRoleColors {\n  harmony: ColorHarmony;\n  colors: readonly GeneratedHarmonyRoleColor[];\n  primary: GeneratedHarmonyRoleColor;\n  secondary?: GeneratedHarmonyRoleColor;\n  tertiary?: GeneratedHarmonyRoleColor;\n  quaternary?: GeneratedHarmonyRoleColor;\n  diagnostics: HarmonyGenerationDiagnostics;\n}\n\n/***\n  Create diagnostics for the reliability of generated hue relationships.\n*/\nfunction createHarmonyGenerationDiagnostics(primaryChroma: number): HarmonyGenerationDiagnostics {\n  const warnings: HarmonyGenerationWarning[] = [];\n  if (primaryChroma === 0) {\n    warnings.push({\n      code: 'achromatic_primary',\n      message:\n        'The selected primary is achromatic, so generated hue relationships are not visible.',\n    });\n  } else if (primaryChroma < MIN_HUEFUL_CHROMA) {\n    warnings.push({\n      code: 'low_chroma_primary',\n      message: 'The selected primary has low chroma, so generated hue relationships may be weak.',\n    });\n  }\n  return {\n    isHueReliable: primaryChroma >= MIN_HUEFUL_CHROMA,\n    primaryChroma,\n    warnings,\n  };\n}\n\n/***\n  Resolve a complete harmony definition from the canonical public catalog.\n*/\nfunction getHarmonyDefinition(harmony: ColorHarmony): ColorHarmonyDefinition {\n  const definition = COLOR_HARMONY_CATALOG.find(({ id }) => id === harmony);\n  if (!definition) {\n    throw new Error(`[color-theory] Missing definition for harmony ${harmony}.`);\n  }\n  return definition;\n}\n\n/***\n  Generate role-based harmony colors from a primary color and harmony strategy.\n*/\nexport function generateHarmonyRoleColors(\n  primaryColor: HexColor,\n  harmony: ColorHarmony,\n): GeneratedHarmonyRoleColors {\n  const base = parseHexToOklch(primaryColor);\n  const definition = getHarmonyDefinition(harmony);\n  const baseHue = normalizeHueDegrees(base.h);\n\n  const colors = definition.roles.map((role, index): GeneratedHarmonyRoleColor => {\n    const hueDegrees = normalizeHueDegrees(baseHue + (definition.offsets.at(index) ?? 0));\n    return {\n      role,\n      hex: role === 'primary' ? primaryColor : oklchToHex({ ...base, h: hueDegrees }),\n      hueDegrees,\n      source: role === 'primary' ? 'selected' : 'generated',\n    };\n  });\n\n  const primary = colors.find((color) => color.role === 'primary');\n  if (!primary) {\n    throw new Error('[color-theory] Expected generated harmony role colors to include primary.');\n  }\n\n  const secondary = colors.find((color) => color.role === 'secondary');\n  const tertiary = colors.find((color) => color.role === 'tertiary');\n  const quaternary = colors.find((color) => color.role === 'quaternary');\n\n  return {\n    harmony,\n    colors,\n    primary,\n    ...(secondary ? { secondary } : {}),\n    ...(tertiary ? { tertiary } : {}),\n    ...(quaternary ? { quaternary } : {}),\n    diagnostics: createHarmonyGenerationDiagnostics(base.c),\n  };\n}\n"]}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './contrast';
 export * from './harmony';
 export * from './hex';
 export * from './neutral';
+export * from './selection';
 export * from './semantic-status';
 export * from './semantics';
 export * from './swatches';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,OAAO,CAAC;AACtB,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,OAAO,CAAC;AACtB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -2,6 +2,7 @@ export * from './contrast';
 export * from './harmony';
 export * from './hex';
 export * from './neutral';
+export * from './selection';
 export * from './semantic-status';
 export * from './semantics';
 export * from './swatches';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,OAAO,CAAC;AACtB,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC","sourcesContent":["export * from './contrast';\nexport * from './harmony';\nexport * from './hex';\nexport * from './neutral';\nexport * from './semantic-status';\nexport * from './semantics';\nexport * from './swatches';\nexport * from './theme-colors';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,OAAO,CAAC;AACtB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC","sourcesContent":["export * from './contrast';\nexport * from './harmony';\nexport * from './hex';\nexport * from './neutral';\nexport * from './selection';\nexport * from './semantic-status';\nexport * from './semantics';\nexport * from './swatches';\nexport * from './theme-colors';\n"]}

package/dist/neutral.d.ts

@@ -1,7 +1,6 @@
-import type { GeneratedHarmonyRoleColors } from './harmony';
+import { type GeneratedHarmonyRoleColors } from './harmony';
 import type { HexColor } from './hex';
 import { type ColorSwatch, type ColorSwatchDiagnostics } from './swatches';
-export declare const MIN_HUEFUL_CHROMA = 0.015;
 export interface NeutralSwatchResult {
     neutralKeyColor: HexColor;
     neutral: ColorSwatch;

package/dist/neutral.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"neutral.d.ts","sourceRoot":"","sources":["../src/neutral.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAC1E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEtC,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAE5B,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,QAAQ,CAAC;IAC1B,OAAO,EAAE,WAAW,CAAC;IACrB,WAAW,EAAE,sBAAsB,CAAC;CACrC;AAED,MAAM,WAAW,wBAAwB;IACvC,eAAe,EAAE,QAAQ,CAAC;IAC1B,WAAW,EAAE,sBAAsB,CAAC;CACrC;AAkCD;;EAEE;AACF,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,0BAA0B,GAAG,mBAAmB,CAuBjG"}
+{"version":3,"file":"neutral.d.ts","sourceRoot":"","sources":["../src/neutral.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,0BAA0B,EAAqB,MAAM,WAAW,CAAC;AAClG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEtC,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAE5B,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,QAAQ,CAAC;IAC1B,OAAO,EAAE,WAAW,CAAC;IACrB,WAAW,EAAE,sBAAsB,CAAC;CACrC;AAED,MAAM,WAAW,wBAAwB;IACvC,eAAe,EAAE,QAAQ,CAAC;IAC1B,WAAW,EAAE,sBAAsB,CAAC;CACrC;AAwBD;;EAEE;AACF,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,0BAA0B,GAAG,mBAAmB,CAuBjG"}

package/dist/neutral.js

@@ -1,22 +1,16 @@
+import { MIN_HUEFUL_CHROMA } from './harmony';
 import { normalizeHueDegrees, oklchToHex, parseHexToOklch } from './internal-culori';
 import { COLOR_SWATCH_BASE_LIGHTNESS, generateColorSwatch, } from './swatches';
-export const MIN_HUEFUL_CHROMA = 0.015;
 /***
   Pick the harmony color that should tint the generated neutral swatch.
 */
 function pickTintSourceHex(roleColors, harmony) {
-    const byMapping = {
-        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);
+    if (harmony === 'monochromatic')
+        return roleColors.primary.hex;
+    if (harmony === 'complementary') {
+        return roleColors.secondary?.hex ?? roleColors.primary.hex;
+    }
+    return roleColors.tertiary?.hex ?? roleColors.secondary?.hex ?? roleColors.primary.hex;
 }
 /***
   Clamp a number to a finite minimum and maximum range.