@trishchuk/coolors-mcp 1.0.0 → 1.1.0

package/docs/concepts/color-spaces.md

@@ -37,7 +37,7 @@ Intuitive color model for human understanding.
 }
 ```
 
-## LAB (CIE L*a*b*)
+## LAB (CIE L*a*b\*)
 
 Perceptually uniform color space based on human vision.
 
@@ -104,33 +104,38 @@ HSL ↔ RGB ↔ HEX
 const hex = "#6366F1";
 
 // To RGB
-"rgb(99, 102, 241)"
+("rgb(99, 102, 241)");
 
 // To HSL
-"hsl(239, 84%, 67%)"
+("hsl(239, 84%, 67%)");
 
 // To LAB
-"lab(47.9, 35.2, -65.7)"
+("lab(47.9, 35.2, -65.7)");
 
 // To HCT
-"hct(265.8, 87.2, 47.9)"
+("hct(265.8, 87.2, 47.9)");
 ```
 
 ## Choosing the Right Color Space
 
 ### For Color Picking
+
 Use **HSL** - intuitive for users to understand and manipulate.
 
 ### For Color Matching
+
 Use **LAB** or **HCT** - perceptually uniform for accurate comparisons.
 
 ### For UI Themes
+
 Use **HCT** - designed for interface design with predictable contrast.
 
 ### For Web/Digital
+
 Use **RGB/Hex** - native format for browsers and displays.
 
 ### For Print
+
 Use **LAB** - device-independent and accurate for print reproduction.
 
 ## Perceptual Distance Metrics
@@ -138,42 +143,53 @@ Use **LAB** - device-independent and accurate for print reproduction.
 Different color spaces affect distance calculations:
 
 ### RGB Distance (Euclidean)
+
 Simple but perceptually inaccurate:
+
 ```
 distance = √((r₂-r₁)² + (g₂-g₁)² + (b₂-b₁)²)
 ```
 
 ### Delta E (LAB-based)
+
 Industry standard for color difference:
+
 - **Delta E 76**: Original formula
 - **Delta E 94**: Improved for textiles
 - **Delta E 2000**: Most accurate, accounts for human perception
 
 ### HCT Distance
+
 Weighted for UI applications:
+
 ```
 distance = √((h₂-h₁)² + (c₂-c₁)² + 2×(t₂-t₁)²)
 ```
+
 Tone is weighted 2x because lightness differences are more noticeable in UI.
 
 ## Color Space Limitations
 
 ### RGB Limitations
+
 - Not perceptually uniform
 - Difficult for humans to predict color changes
 - Poor for color difference calculations
 
 ### HSL Limitations
+
 - Saturation and lightness are not perceptually uniform
 - Colors with same L value may appear different brightness
 - Not suitable for accessibility calculations
 
 ### LAB Limitations
+
 - Can represent impossible colors
 - Less intuitive for designers
 - Blue region has known inaccuracies
 
 ### HCT Advantages
+
 - Specifically designed for UI/UX
 - Predictable contrast ratios
 - Perceptually uniform
@@ -182,7 +198,9 @@ Tone is weighted 2x because lightness differences are more noticeable in UI.
 ## Practical Applications
 
 ### Theme Generation
+
 HCT enables predictable theme generation:
+
 ```javascript
 // Generate accessible color variations
 const baseHCT = { h: 265, c: 50, t: 50 };
@@ -195,13 +213,17 @@ const dark = { ...baseHCT, t: 20 };
 ```
 
 ### Color Harmonies
+
 Different spaces excel at different harmonies:
+
 - **HSL**: Best for analogous colors (rotate hue)
 - **HCT**: Best for tonal variations (adjust tone)
 - **LAB**: Best for perceptual interpolation
 
 ### Gradient Generation
+
 Color space affects gradient smoothness:
+
 - **RGB**: Can produce muddy colors in middle
 - **HSL**: Can produce unnatural brightness shifts
 - **LAB/HCT**: Smooth perceptual transitions
@@ -219,4 +241,4 @@ Color space affects gradient smoothness:
 - [HCT Color System](./hct.md) - Deep dive into HCT
 - [Material Design](./material-design.md) - Using HCT in practice
 - [Accessibility](./accessibility.md) - Color contrast and WCAG
-- [Theme Matching](./theme-matching.md) - Algorithm details
+- [Theme Matching](./theme-matching.md) - Algorithm details

package/docs/concepts/distance-metrics.md

@@ -17,16 +17,19 @@ distance = √((r₂-r₁)² + (g₂-g₁)² + (b₂-b₁)²)
 ```
 
 **Pros:**
+
 - Fast to compute
 - Simple to understand
 - Good for rough comparisons
 
 **Cons:**
+
 - Not perceptually uniform
 - Poor for subtle color differences
 - Doesn't match human vision
 
 **When to use:**
+
 - Quick filtering
 - Performance-critical applications
 - When accuracy isn't crucial
@@ -40,11 +43,13 @@ The original perceptual color difference formula using LAB color space:
 ```
 
 **Characteristics:**
+
 - First attempt at perceptual uniformity
 - Simple LAB distance calculation
 - Threshold: ΔE < 2.3 is barely perceptible
 
 **When to use:**
+
 - Basic perceptual matching
 - Legacy systems
 - When computation speed matters
@@ -58,11 +63,13 @@ Improved formula with weighting factors for different color attributes:
 ```
 
 **Improvements:**
+
 - Separate weights for lightness, chroma, hue
 - Better for textiles and graphics
 - More accurate than CIE76
 
 **When to use:**
+
 - Textile industry
 - Graphic arts
 - Better accuracy than CIE76
@@ -77,12 +84,14 @@ The most accurate standard for color difference, addressing perceptual non-unifo
 ```
 
 **Features:**
+
 - Rotation term for blue region
 - Lightness, chroma, hue corrections
 - Most accurate for human perception
 - Industry standard
 
 **When to use:**
+
 - Color matching applications
 - Quality control
 - When accuracy is paramount
@@ -98,11 +107,13 @@ distance = √((Δh × wₕ)² + (Δc × wᴄ)² + (Δt × wᴛ)²)
 ```
 
 **Advantages:**
+
 - Optimized for UI colors
 - Tone component predicts contrast
 - Better for Material Design
 
 **When to use:**
+
 - UI/UX design
 - Material Design systems
 - Theme matching
@@ -112,14 +123,14 @@ distance = √((Δh × wₕ)² + (Δc × wᴄ)² + (Δt × wᴛ)²)
 
 Different ΔE values represent different levels of color difference:
 
-| ΔE Value | Perception | Use Case |
-|----------|------------|----------|
-| 0-1 | Not perceptible | Exact matches |
-| 1-2 | Barely perceptible | Very close matches |
-| 2-3.5 | Perceptible by experts | Close matches |
-| 3.5-5 | Noticeable difference | Acceptable matches |
-| 5-10 | Clear difference | Related colors |
-| >10 | Different colors | Distinct colors |
+| ΔE Value | Perception             | Use Case           |
+| -------- | ---------------------- | ------------------ |
+| 0-1      | Not perceptible        | Exact matches      |
+| 1-2      | Barely perceptible     | Very close matches |
+| 2-3.5    | Perceptible by experts | Close matches      |
+| 3.5-5    | Noticeable difference  | Acceptable matches |
+| 5-10     | Clear difference       | Related colors     |
+| >10      | Different colors       | Distinct colors    |
 
 ## Metric Comparison
 
@@ -211,14 +222,14 @@ Is performance critical?
 
 ### Use Case Guidelines
 
-| Use Case | Recommended Metric | Reason |
-|----------|-------------------|---------|
-| CSS color matching | Delta E 2000 | Accuracy |
-| Real-time filtering | Euclidean | Speed |
-| Theme generation | HCT | UI optimization |
-| Print color matching | Delta E 2000 | Industry standard |
-| Palette creation | HCT | Perceptual uniformity |
-| Image quantization | Delta E 76 | Balance |
+| Use Case             | Recommended Metric | Reason                |
+| -------------------- | ------------------ | --------------------- |
+| CSS color matching   | Delta E 2000       | Accuracy              |
+| Real-time filtering  | Euclidean          | Speed                 |
+| Theme generation     | HCT                | UI optimization       |
+| Print color matching | Delta E 2000       | Industry standard     |
+| Palette creation     | HCT                | Perceptual uniformity |
+| Image quantization   | Delta E 76         | Balance               |
 
 ## Implementation Examples
 
@@ -226,14 +237,14 @@ Is performance critical?
 
 ```javascript
 function findSimilarColors(targetColor, palette, threshold = 5) {
-  return palette.filter(color => {
-    const distance = colorDistance(targetColor, color, 'deltaE2000');
+  return palette.filter((color) => {
+    const distance = colorDistance(targetColor, color, "deltaE2000");
     return distance < threshold;
   });
 }
 
 // Usage
-const similar = findSimilarColors('#6366f1', myPalette, 10);
+const similar = findSimilarColors("#6366f1", myPalette, 10);
 // Returns colors within ΔE 10 of target
 ```
 
@@ -243,11 +254,11 @@ const similar = findSimilarColors('#6366f1', myPalette, 10);
 function clusterColors(colors, maxDistance = 5) {
   const clusters = [];
 
-  colors.forEach(color => {
+  colors.forEach((color) => {
     let added = false;
 
     for (const cluster of clusters) {
-      const distance = colorDistance(color, cluster.center, 'deltaE2000');
+      const distance = colorDistance(color, cluster.center, "deltaE2000");
       if (distance < maxDistance) {
         cluster.colors.push(color);
         added = true;
@@ -258,7 +269,7 @@ function clusterColors(colors, maxDistance = 5) {
     if (!added) {
       clusters.push({
         center: color,
-        colors: [color]
+        colors: [color],
       });
     }
   });
@@ -281,7 +292,7 @@ function interpolatePerceptual(color1, color2, steps) {
     const lab = {
       l: lab1.l + (lab2.l - lab1.l) * t,
       a: lab1.a + (lab2.a - lab1.a) * t,
-      b: lab1.b + (lab2.b - lab1.b) * t
+      b: lab1.b + (lab2.b - lab1.b) * t,
     };
     colors.push(labToRgb(lab));
   }
@@ -313,16 +324,16 @@ Distance perception changes based on viewing conditions:
 
 ```javascript
 function contextualDistance(color1, color2, context) {
-  switch(context) {
-    case 'small-text':
+  switch (context) {
+    case "small-text":
       // Need larger differences for readability
       return colorDistance(color1, color2) * 1.5;
 
-    case 'large-area':
+    case "large-area":
       // Subtle differences more noticeable
       return colorDistance(color1, color2) * 0.8;
 
-    case 'dark-mode':
+    case "dark-mode":
       // Adjust for dark backgrounds
       return adjustedDarkModeDistance(color1, color2);
 
@@ -343,8 +354,8 @@ function multiFactorDistance(color1, color2) {
   const semantic = getSemanticDistance(color1, color2);
 
   return {
-    overall: (perceptual * 0.6 + contrast * 0.3 + semantic * 0.1),
-    components: { perceptual, contrast, semantic }
+    overall: perceptual * 0.6 + contrast * 0.3 + semantic * 0.1,
+    components: { perceptual, contrast, semantic },
   };
 }
 ```
@@ -352,18 +363,22 @@ function multiFactorDistance(color1, color2) {
 ## Common Pitfalls
 
 ### RGB Distance Misuse
+
 ❌ Don't use RGB distance for perceptual matching
 ✅ Use Delta E or HCT distance instead
 
 ### Ignoring Context
+
 ❌ Don't use the same threshold for all use cases
 ✅ Adjust thresholds based on application
 
 ### Over-Engineering
+
 ❌ Don't always use the most complex metric
 ✅ Choose based on actual requirements
 
 ### Wrong Color Space
+
 ❌ Don't interpolate in RGB for gradients
 ✅ Use LAB or HCT for smooth transitions
 
@@ -381,4 +396,4 @@ function multiFactorDistance(color1, color2) {
 - [Color Spaces](./color-spaces.md) - Understanding different color models
 - [HCT System](./hct.md) - Google's perceptual color space
 - [Theme Matching](./theme-matching.md) - Using distance for matching
-- [Accessibility](./accessibility.md) - Contrast and perception
+- [Accessibility](./accessibility.md) - Contrast and perception

package/docs/concepts/hct.md

@@ -50,7 +50,7 @@ Tone Difference | Approximate Contrast Ratio
 const primary = { h: 265, c: 50, t: 50 };
 
 // Guaranteed accessible combinations
-const onPrimary = { h: 265, c: 50, t: 100 };     // t: 50 → 100 = 50 diff = 4.5:1
+const onPrimary = { h: 265, c: 50, t: 100 }; // t: 50 → 100 = 50 diff = 4.5:1
 const primaryContainer = { h: 265, c: 25, t: 90 }; // Lower chroma, high tone
 const onPrimaryContainer = { h: 265, c: 50, t: 10 }; // t: 90 → 10 = 80 diff = 7:1+
 ```
@@ -62,11 +62,13 @@ HCT is the foundation of Material Design 3's color system:
 ### Tonal Palettes
 
 Material Design uses 13 standard tones:
+
 ```
 [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100]
 ```
 
 Each tone has specific use cases:
+
 - **0-10**: On-colors for light surfaces
 - **20-40**: Accent and emphasis colors
 - **50**: Medium, often primary color
@@ -79,16 +81,16 @@ HCT enables semantic color roles with guaranteed contrast:
 
 ```javascript
 // Primary color family
-primary: tone(40)           // Main brand color
-onPrimary: tone(100)        // Text on primary
-primaryContainer: tone(90)  // Light container
-onPrimaryContainer: tone(10) // Text on container
+primary: tone(40); // Main brand color
+onPrimary: tone(100); // Text on primary
+primaryContainer: tone(90); // Light container
+onPrimaryContainer: tone(10); // Text on container
 
 // Surface colors
-surface: tone(99)           // Main background
-onSurface: tone(10)         // Text on surface
-surfaceVariant: tone(95)   // Secondary background
-onSurfaceVariant: tone(30) // Secondary text
+surface: tone(99); // Main background
+onSurface: tone(10); // Text on surface
+surfaceVariant: tone(95); // Secondary background
+onSurfaceVariant: tone(30); // Secondary text
 ```
 
 ## Chroma Behavior
@@ -106,6 +108,7 @@ Chroma in HCT represents color intensity, but unlike saturation in HSL, it maint
 ### Chroma and Tone Interaction
 
 Maximum achievable chroma varies by tone:
+
 ```
 Tone 0-10:   Low max chroma (dark colors can't be very colorful)
 Tone 40-60:  Highest max chroma (mid-tones most colorful)
@@ -128,7 +131,7 @@ function generateTheme(sourceColor) {
     tertiary: { h: hct.h + 120, c: hct.c * 0.7, t: 40 },
     error: { h: 25, c: 84, t: 40 },
     neutral: { h: hct.h, c: 4, t: 50 },
-    neutralVariant: { h: hct.h, c: 8, t: 50 }
+    neutralVariant: { h: hct.h, c: 8, t: 50 },
   };
 }
 ```
@@ -139,8 +142,7 @@ Create accessible color variations:
 
 ```javascript
 function createAccessiblePair(baseHct, contrastRatio = 4.5) {
-  const toneDiff = contrastRatio >= 7 ? 70 :
-                   contrastRatio >= 4.5 ? 50 : 40;
+  const toneDiff = contrastRatio >= 7 ? 70 : contrastRatio >= 4.5 ? 50 : 40;
 
   const lighter = { ...baseHct, t: Math.min(100, baseHct.t + toneDiff) };
   const darker = { ...baseHct, t: Math.max(0, baseHct.t - toneDiff) };
@@ -172,21 +174,21 @@ function harmonize(color1Hct, color2Hct) {
 
 ### HCT vs LAB
 
-| Aspect | HCT | LAB |
-|--------|-----|-----|
-| Perceptual Uniformity | ✅ Optimized for UI | ✅ General purpose |
-| Contrast Prediction | ✅ Direct tone mapping | ❌ Requires calculation |
-| UI Optimization | ✅ Designed for screens | ❌ Designed for all media |
-| Impossible Colors | ❌ None | ✅ Can represent |
+| Aspect                | HCT                     | LAB                       |
+| --------------------- | ----------------------- | ------------------------- |
+| Perceptual Uniformity | ✅ Optimized for UI     | ✅ General purpose        |
+| Contrast Prediction   | ✅ Direct tone mapping  | ❌ Requires calculation   |
+| UI Optimization       | ✅ Designed for screens | ❌ Designed for all media |
+| Impossible Colors     | ❌ None                 | ✅ Can represent          |
 
 ### HCT vs HSL
 
-| Aspect | HCT | HSL |
-|--------|-----|-----|
-| Perceptual Uniformity | ✅ Yes | ❌ No |
-| Lightness Accuracy | ✅ Perceptual | ❌ Mathematical |
-| Contrast Prediction | ✅ Built-in | ❌ Requires calculation |
-| Designer Familiarity | 🔶 Learning curve | ✅ Well known |
+| Aspect                | HCT               | HSL                     |
+| --------------------- | ----------------- | ----------------------- |
+| Perceptual Uniformity | ✅ Yes            | ❌ No                   |
+| Lightness Accuracy    | ✅ Perceptual     | ❌ Mathematical         |
+| Contrast Prediction   | ✅ Built-in       | ❌ Requires calculation |
+| Designer Familiarity  | 🔶 Learning curve | ✅ Well known           |
 
 ## Advanced Concepts
 
@@ -197,6 +199,7 @@ HCT is built on the CAM16 color appearance model, which models how humans percei
 ### Viewing Conditions
 
 HCT assumes standard viewing conditions:
+
 - Average surround
 - Adapting luminance of 200 cd/m²
 - 20% background luminance
@@ -238,9 +241,9 @@ const darkSurface = { h: 265, c: 0, t: 10 };
 
 ```javascript
 // Standard error colors in HCT
-const error = { h: 25, c: 84, t: 40 };        // Red-orange, high chroma
+const error = { h: 25, c: 84, t: 40 }; // Red-orange, high chroma
 const errorContainer = { h: 25, c: 30, t: 90 }; // Muted, light
-const onError = { h: 25, c: 0, t: 100 };      // White
+const onError = { h: 25, c: 0, t: 100 }; // White
 const onErrorContainer = { h: 25, c: 84, t: 10 }; // Dark red
 ```
 
@@ -258,4 +261,4 @@ Coolors MCP implements HCT using Google's Material Color Utilities algorithms:
 - [Color Spaces](./color-spaces.md) - Comparison with other color models
 - [Material Design](./material-design.md) - HCT in Material Design 3
 - [Accessibility](./accessibility.md) - Using tone for contrast
-- [Theme Matching](./theme-matching.md) - HCT-based matching algorithm
+- [Theme Matching](./theme-matching.md) - HCT-based matching algorithm