@trishchuk/coolors-mcp 1.0.0

package/docs/concepts/color-spaces.md

@@ -0,0 +1,222 @@
+# Color Spaces
+
+Understanding different color spaces is crucial for professional color operations. Each color space has its strengths and optimal use cases.
+
+## RGB (Red, Green, Blue)
+
+The fundamental color model for digital displays.
+
+- **Range**: 0-255 for each channel
+- **Use Cases**: Screen display, web colors
+- **Format**: `rgb(255, 99, 71)` or `#FF6347`
+
+```javascript
+// RGB representation
+{
+  r: 255,  // Red channel (0-255)
+  g: 99,   // Green channel (0-255)
+  b: 71    // Blue channel (0-255)
+}
+```
+
+## HSL (Hue, Saturation, Lightness)
+
+Intuitive color model for human understanding.
+
+- **Hue**: 0-360° (color wheel position)
+- **Saturation**: 0-100% (color purity)
+- **Lightness**: 0-100% (brightness)
+- **Use Cases**: Color picking, theme generation
+
+```javascript
+// HSL representation
+{
+  h: 9,    // Hue in degrees
+  s: 100,  // Saturation percentage
+  l: 64    // Lightness percentage
+}
+```
+
+## LAB (CIE L*a*b*)
+
+Perceptually uniform color space based on human vision.
+
+- **L**: Lightness (0-100)
+- **a**: Green-red axis (-128 to 127)
+- **b**: Blue-yellow axis (-128 to 127)
+- **Use Cases**: Color difference calculations, print
+
+```javascript
+// LAB representation
+{
+  l: 62.2,  // Lightness
+  a: 57.8,  // Green-red component
+  b: 46.4   // Blue-yellow component
+}
+```
+
+## HCT (Hue, Chroma, Tone)
+
+Google's perceptually uniform color space, optimized for UI.
+
+- **Hue**: 0-360° (color wheel position)
+- **Chroma**: 0-120+ (color intensity)
+- **Tone**: 0-100 (perceptual lightness)
+- **Use Cases**: Material Design, UI theming
+
+### Why HCT is Superior for UI
+
+1. **Predictable Contrast**: Tone values directly correlate with WCAG contrast ratios
+   - 40 tone difference ≈ 3:1 contrast
+   - 50 tone difference ≈ 4.5:1 contrast
+
+2. **Perceptual Uniformity**: Equal changes in values produce equal perceptual changes
+
+3. **UI-Optimized**: Designed specifically for interface design, not general color science
+
+```javascript
+// HCT representation
+{
+  h: 25.5,   // Hue in degrees
+  c: 48.2,   // Chroma (color intensity)
+  t: 67.5    // Tone (perceptual lightness)
+}
+```
+
+## Color Space Conversions
+
+Coolors MCP handles all conversions through RGB as the central format:
+
+```
+HSL ↔ RGB ↔ HEX
+     ↓ ↑
+    XYZ
+     ↓ ↑
+    LAB
+     ↓ ↑
+    HCT
+```
+
+### Conversion Examples
+
+```javascript
+// Convert hex to multiple formats
+const hex = "#6366F1";
+
+// To RGB
+"rgb(99, 102, 241)"
+
+// To HSL
+"hsl(239, 84%, 67%)"
+
+// To LAB
+"lab(47.9, 35.2, -65.7)"
+
+// To HCT
+"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
+
+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
+- No impossible colors
+
+## Practical Applications
+
+### Theme Generation
+HCT enables predictable theme generation:
+```javascript
+// Generate accessible color variations
+const baseHCT = { h: 265, c: 50, t: 50 };
+
+// Light variant (3:1 contrast)
+const light = { ...baseHCT, t: 90 };
+
+// Dark variant (4.5:1 contrast)
+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
+
+## Best Practices
+
+1. **Store colors in RGB/Hex** for compatibility
+2. **Convert to HCT** for manipulation and theming
+3. **Use LAB/Delta E** for color matching
+4. **Display in HSL** for user interfaces
+5. **Calculate contrast** in relative luminance
+
+## See Also
+
+- [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

package/docs/concepts/distance-metrics.md

@@ -0,0 +1,384 @@
+# Distance Metrics
+
+Understanding how to measure the difference between colors is crucial for color matching, palette generation, and theme creation. Different metrics serve different purposes.
+
+## Overview
+
+Color distance metrics quantify how different two colors appear. The challenge is that simple mathematical distance doesn't match human perception - two colors that are numerically similar might look very different, and vice versa.
+
+## Available Metrics
+
+### Euclidean Distance (RGB)
+
+The simplest metric, calculating straight-line distance in RGB space:
+
+```javascript
+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
+
+### Delta E CIE76
+
+The original perceptual color difference formula using LAB color space:
+
+```javascript
+ΔE*₇₆ = √((L₂-L₁)² + (a₂-a₁)² + (b₂-b₁)²)
+```
+
+**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
+
+### Delta E CIE94
+
+Improved formula with weighting factors for different color attributes:
+
+```javascript
+ΔE*₉₄ = √((ΔL/kₗSₗ)² + (ΔC/kᴄSᴄ)² + (ΔH/kₕSₕ)²)
+```
+
+**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
+
+### Delta E 2000 (CIEDE2000)
+
+The most accurate standard for color difference, addressing perceptual non-uniformities:
+
+```javascript
+// Complex formula with multiple correction factors
+ΔE*₀₀ = √((ΔL'/kₗSₗ)² + (ΔC'/kᴄSᴄ)² + (ΔH'/kₕSₕ)² + Rᴛ(ΔC'/kᴄSᴄ)(ΔH'/kₕSₕ))
+```
+
+**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
+- Default for most use cases
+
+### HCT Distance
+
+Weighted distance in Google's HCT color space:
+
+```javascript
+distance = √((Δh × wₕ)² + (Δc × wᴄ)² + (Δt × wᴛ)²)
+// Typical weights: wₕ=1, wᴄ=1, wᴛ=2
+```
+
+**Advantages:**
+- Optimized for UI colors
+- Tone component predicts contrast
+- Better for Material Design
+
+**When to use:**
+- UI/UX design
+- Material Design systems
+- Theme matching
+- Accessibility considerations
+
+## Perceptibility Thresholds
+
+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 |
+
+## Metric Comparison
+
+### Performance Comparison
+
+```javascript
+// Relative computation time (normalized)
+{
+  "euclidean": 1,      // Baseline
+  "deltaE76": 2,       // 2x slower
+  "deltaE94": 3,       // 3x slower
+  "deltaE2000": 10,    // 10x slower
+  "hct": 4             // 4x slower
+}
+```
+
+### Accuracy Comparison
+
+```javascript
+// Correlation with human perception (0-1)
+{
+  "euclidean": 0.65,   // Poor
+  "deltaE76": 0.75,    // Fair
+  "deltaE94": 0.85,    // Good
+  "deltaE2000": 0.95,  // Excellent
+  "hct": 0.90          // Very good for UI
+}
+```
+
+## Using Distance Metrics in Coolors MCP
+
+### Basic Color Distance
+
+```javascript
+// Using Delta E 2000 (default)
+{
+  "name": "color_distance",
+  "arguments": {
+    "color1": "#6366f1",
+    "color2": "#5355d1"
+  }
+}
+// Result: 5.2 (noticeable but related)
+
+// Using specific metric
+{
+  "name": "color_distance",
+  "arguments": {
+    "color1": "#6366f1",
+    "color2": "#5355d1",
+    "metric": "euclidean"
+  }
+}
+// Result: 32.5 (less meaningful number)
+```
+
+### Weighted HCT Distance
+
+```javascript
+// Custom weights for UI matching
+{
+  "name": "color_distance",
+  "arguments": {
+    "color1": "#6366f1",
+    "color2": "#5355d1",
+    "metric": "weighted",
+    "weights": {
+      "hue": 1,
+      "chroma": 1,
+      "tone": 2  // Emphasize lightness
+    }
+  }
+}
+```
+
+## Choosing the Right Metric
+
+### Decision Tree
+
+```
+Is performance critical?
+├─ Yes → Euclidean
+└─ No → Is it for UI/UX?
+    ├─ Yes → HCT Distance
+    └─ No → Need maximum accuracy?
+        ├─ Yes → Delta E 2000
+        └─ No → Delta E 76
+```
+
+### 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 |
+
+## Implementation Examples
+
+### Finding Similar Colors
+
+```javascript
+function findSimilarColors(targetColor, palette, threshold = 5) {
+  return palette.filter(color => {
+    const distance = colorDistance(targetColor, color, 'deltaE2000');
+    return distance < threshold;
+  });
+}
+
+// Usage
+const similar = findSimilarColors('#6366f1', myPalette, 10);
+// Returns colors within ΔE 10 of target
+```
+
+### Color Clustering
+
+```javascript
+function clusterColors(colors, maxDistance = 5) {
+  const clusters = [];
+
+  colors.forEach(color => {
+    let added = false;
+
+    for (const cluster of clusters) {
+      const distance = colorDistance(color, cluster.center, 'deltaE2000');
+      if (distance < maxDistance) {
+        cluster.colors.push(color);
+        added = true;
+        break;
+      }
+    }
+
+    if (!added) {
+      clusters.push({
+        center: color,
+        colors: [color]
+      });
+    }
+  });
+
+  return clusters;
+}
+```
+
+### Perceptual Interpolation
+
+```javascript
+function interpolatePerceptual(color1, color2, steps) {
+  // Convert to LAB for perceptual interpolation
+  const lab1 = rgbToLab(color1);
+  const lab2 = rgbToLab(color2);
+
+  const colors = [];
+  for (let i = 0; i <= steps; i++) {
+    const t = i / 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
+    };
+    colors.push(labToRgb(lab));
+  }
+
+  return colors;
+}
+```
+
+## Advanced Concepts
+
+### Weighted Metrics
+
+Different applications benefit from custom weightings:
+
+```javascript
+// UI Design - emphasize tone differences
+const uiWeights = { lightness: 2, chroma: 1, hue: 0.5 };
+
+// Brand Colors - emphasize hue accuracy
+const brandWeights = { lightness: 1, chroma: 1.5, hue: 2 };
+
+// Accessibility - focus on lightness
+const a11yWeights = { lightness: 3, chroma: 0.5, hue: 0.5 };
+```
+
+### Context-Aware Distance
+
+Distance perception changes based on viewing conditions:
+
+```javascript
+function contextualDistance(color1, color2, context) {
+  switch(context) {
+    case 'small-text':
+      // Need larger differences for readability
+      return colorDistance(color1, color2) * 1.5;
+
+    case 'large-area':
+      // Subtle differences more noticeable
+      return colorDistance(color1, color2) * 0.8;
+
+    case 'dark-mode':
+      // Adjust for dark backgrounds
+      return adjustedDarkModeDistance(color1, color2);
+
+    default:
+      return colorDistance(color1, color2);
+  }
+}
+```
+
+### Multi-Dimensional Distance
+
+Sometimes you need to consider multiple factors:
+
+```javascript
+function multiFactorDistance(color1, color2) {
+  const perceptual = deltaE2000(color1, color2);
+  const contrast = Math.abs(getContrast(color1) - getContrast(color2));
+  const semantic = getSemanticDistance(color1, color2);
+
+  return {
+    overall: (perceptual * 0.6 + contrast * 0.3 + semantic * 0.1),
+    components: { perceptual, contrast, semantic }
+  };
+}
+```
+
+## 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
+
+## Best Practices
+
+1. **Start with Delta E 2000** - It's the most accurate general-purpose metric
+2. **Use HCT for UI** - Better for interface design and accessibility
+3. **Cache computations** - Distance calculations can be expensive
+4. **Test with real users** - Perception varies between individuals
+5. **Consider viewing conditions** - Screen, lighting affect perception
+6. **Document your choice** - Explain why you chose a specific metric
+
+## See Also
+
+- [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