@trishchuk/coolors-mcp 1.0.0

package/docs/concepts/hct.md

@@ -0,0 +1,261 @@
+# HCT Color System
+
+HCT (Hue, Chroma, Tone) is Google's perceptually uniform color space, specifically designed for user interface applications. It forms the foundation of Material Design 3's dynamic color system.
+
+## What is HCT?
+
+HCT is a color space that combines the best aspects of LAB (perceptual uniformity) with practical considerations for UI design:
+
+- **Hue** (0-360°): The color's position on the color wheel
+- **Chroma** (0-120+): The color's intensity or purity
+- **Tone** (0-100): The color's perceptual lightness
+
+## Why HCT?
+
+### Problem with Traditional Color Spaces
+
+Traditional color spaces have significant limitations for UI design:
+
+1. **RGB**: Not perceptually uniform; equal numeric changes don't produce equal visual changes
+2. **HSL**: Lightness is not perceptually accurate; colors with same L can appear very different
+3. **LAB**: While perceptually uniform, it's not optimized for UI contrast requirements
+
+### HCT's Solutions
+
+HCT addresses these issues with UI-specific optimizations:
+
+1. **Predictable Contrast**: Tone values directly correlate with WCAG contrast ratios
+2. **Perceptual Uniformity**: Equal changes produce equal perceptual differences
+3. **No Impossible Colors**: All HCT values represent real, displayable colors
+4. **Chroma Preservation**: Maintains color intensity across tone changes better than HSL
+
+## Tone and Contrast
+
+The most powerful feature of HCT is the predictable relationship between tone values and contrast ratios:
+
+### Contrast Guarantees
+
+```
+Tone Difference | Approximate Contrast Ratio
+----------------|---------------------------
+      40        |         3:1 (WCAG AA large text)
+      50        |         4.5:1 (WCAG AA normal text)
+      70        |         7:1 (WCAG AAA)
+```
+
+### Example: Accessible Color Pairs
+
+```javascript
+// Base color
+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 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+
+```
+
+## Material Design Integration
+
+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
+- **60-80**: Containers and surfaces
+- **90-100**: Backgrounds and on-colors for dark surfaces
+
+### Color Roles
+
+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
+
+// Surface colors
+surface: tone(99)           // Main background
+onSurface: tone(10)         // Text on surface
+surfaceVariant: tone(95)   // Secondary background
+onSurfaceVariant: tone(30) // Secondary text
+```
+
+## Chroma Behavior
+
+Chroma in HCT represents color intensity, but unlike saturation in HSL, it maintains perceptual consistency:
+
+### Chroma Ranges
+
+- **0-20**: Neutral, grayscale colors
+- **20-40**: Muted, subtle colors
+- **40-60**: Moderate intensity (recommended for UI)
+- **60-80**: Vibrant colors
+- **80+**: Very vibrant (use sparingly)
+
+### 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)
+Tone 90-100: Low max chroma (light colors can't be very colorful)
+```
+
+## Practical Applications
+
+### 1. Theme Generation
+
+Generate a complete theme from a single color:
+
+```javascript
+function generateTheme(sourceColor) {
+  const hct = toHct(sourceColor);
+
+  return {
+    primary: { ...hct, t: 40 },
+    secondary: { h: hct.h + 60, c: hct.c * 0.5, t: 40 },
+    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 }
+  };
+}
+```
+
+### 2. Accessible Color Variations
+
+Create accessible color variations:
+
+```javascript
+function createAccessiblePair(baseHct, contrastRatio = 4.5) {
+  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) };
+
+  return baseHct.t > 50 ? darker : lighter;
+}
+```
+
+### 3. Color Harmonization
+
+Harmonize colors to work together:
+
+```javascript
+function harmonize(color1Hct, color2Hct) {
+  // Adjust hues to be more harmonious
+  const hueDiff = Math.abs(color2Hct.h - color1Hct.h);
+
+  if (hueDiff > 180) {
+    // Colors are opposite, increase harmony
+    const targetHue = color1Hct.h + (hueDiff > 270 ? 60 : -60);
+    return { ...color2Hct, h: targetHue };
+  }
+
+  return color2Hct;
+}
+```
+
+## HCT vs Other Color Spaces
+
+### 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 |
+
+### 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 |
+
+## Advanced Concepts
+
+### CAM16 Foundation
+
+HCT is built on the CAM16 color appearance model, which models how humans perceive color under different viewing conditions.
+
+### Viewing Conditions
+
+HCT assumes standard viewing conditions:
+- Average surround
+- Adapting luminance of 200 cd/m²
+- 20% background luminance
+- D65 white point
+
+### Gamut Mapping
+
+HCT automatically maps colors to the sRGB gamut, ensuring all colors are displayable:
+
+```javascript
+// HCT handles gamut mapping internally
+const vibrantHct = { h: 120, c: 200, t: 50 }; // Very high chroma
+const displayable = hctToRgb(vibrantHct); // Automatically in gamut
+```
+
+## Best Practices
+
+1. **Use standard tones** for consistency with Material Design
+2. **Maintain 50+ tone difference** for text on backgrounds
+3. **Keep chroma between 40-60** for most UI elements
+4. **Use lower chroma (4-16)** for neutral colors
+5. **Test with different tones** to ensure accessibility
+
+## Common Patterns
+
+### Dark/Light Theme Switching
+
+```javascript
+// Light theme
+const lightPrimary = { h: 265, c: 50, t: 40 };
+const lightSurface = { h: 265, c: 0, t: 99 };
+
+// Dark theme (invert tones)
+const darkPrimary = { h: 265, c: 50, t: 80 };
+const darkSurface = { h: 265, c: 0, t: 10 };
+```
+
+### Error States
+
+```javascript
+// Standard error colors in HCT
+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 onErrorContainer = { h: 25, c: 84, t: 10 }; // Dark red
+```
+
+## Implementation Details
+
+Coolors MCP implements HCT using Google's Material Color Utilities algorithms:
+
+1. **Color Conversion**: Accurate CAM16 to/from RGB conversion
+2. **Gamut Mapping**: Automatic sRGB gamut clipping
+3. **Tone Mapping**: Precise tone to luminance conversion
+4. **Chroma Maximization**: Finding maximum chroma for any hue/tone
+
+## See Also
+
+- [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

package/docs/concepts/image-analysis.md

@@ -0,0 +1,396 @@
+# Image Color Analysis
+
+Coolors MCP provides advanced image color extraction using Google's Material Color Utilities algorithms, enabling dynamic theme generation from images.
+
+## Overview
+
+Image color extraction involves:
+1. **Quantization** - Reducing colors to a representative set
+2. **Scoring** - Evaluating colors for UI suitability
+3. **Selection** - Choosing optimal source colors
+4. **Theme Generation** - Creating complete color schemes
+
+## The Extraction Process
+
+### 1. Quantization
+
+Quantization is a lossy compression process that selects a limited number of colors that best represent the original image.
+
+#### Celebi Algorithm
+Coolors MCP uses the Celebi quantizer, which combines:
+- **Wu's algorithm**: Fast color quantization
+- **WSMeans**: Weighted spatial color clustering
+
+```javascript
+// Extract up to 128 representative colors
+const colors = quantize(pixels, 128);
+```
+
+#### How It Works
+1. **Spatial clustering**: Groups similar colors that appear near each other
+2. **Color frequency**: Weights colors by how often they appear
+3. **Perceptual grouping**: Merges perceptually similar colors
+4. **Output**: Typically 5-128 distinct colors
+
+### 2. Color Scoring
+
+Not all colors are suitable for UI themes. The scoring algorithm evaluates colors based on:
+
+#### Key Metrics
+
+**Chroma Score**
+Colors closer to the target chroma of 48 receive higher scores:
+```javascript
+chromaScore = 1 - Math.abs(chroma - 48) / 48;
+```
+
+**Population Score**
+More frequent colors score higher:
+```javascript
+populationScore = pixelCount / totalPixels;
+```
+
+**Color Diversity**
+Promotes visually distinct colors:
+- Higher scores for well-represented hues (30° neighborhood)
+- Penalizes colors too similar to already selected ones
+- Ensures good distribution across color wheel
+
+#### Filtering Criteria
+Colors are filtered out if they:
+- Have very low chroma (<15) - too close to grayscale
+- Are extremely rare (<0.01% of pixels)
+- Fall in the "dislike zone" (dark yellow-greens)
+- Are too similar to already selected colors
+
+### 3. Source Color Selection
+
+The system selects multiple source colors for theme options:
+
+```javascript
+// Typical selection process
+1. Extract and score all colors
+2. Select top-scoring distinct colors (usually 3-5)
+3. Present as theme options to user
+4. Use selected color as source for theme generation
+```
+
+## Image Sources
+
+### Wallpapers
+User device wallpapers provide personalized color schemes:
+- Analyzed on device for privacy
+- Updates dynamically when wallpaper changes
+- Creates cohesive system-wide theming
+
+### App Content
+Content-based colors adapt to current context:
+- **Album art** → Music player theme
+- **Product images** → E-commerce theme
+- **Video thumbnails** → Media player theme
+- **Logos** → Brand-consistent theme
+
+### User Photos
+Personal photos for custom themes:
+- Profile pictures for personal spaces
+- Gallery images for creative apps
+- Artwork for design applications
+
+## Implementation
+
+### Basic Extraction
+
+```javascript
+{
+  "name": "extract_image_colors",
+  "arguments": {
+    "imageData": [/* RGBA pixel array */],
+    "maxColors": 5
+  }
+}
+
+// Returns
+{
+  "colors": [
+    { "hex": "#6366f1", "population": 0.23, "score": 0.89 },
+    { "hex": "#ec4899", "population": 0.15, "score": 0.76 },
+    { "hex": "#10b981", "population": 0.12, "score": 0.71 }
+  ]
+}
+```
+
+### Theme from Image
+
+```javascript
+{
+  "name": "generate_theme_from_image",
+  "arguments": {
+    "imageData": [/* RGBA pixel array */],
+    "variant": "tonalSpot"
+  }
+}
+
+// Returns complete Material Design theme
+{
+  "source": "#6366f1",
+  "schemes": {
+    "light": { /* light theme colors */ },
+    "dark": { /* dark theme colors */ }
+  }
+}
+```
+
+## Advanced Features
+
+### Dislike Color Detection
+
+The system automatically detects and adjusts universally disliked colors:
+
+#### The "Bile Zone"
+Dark yellow-greens (reminiscent of biological waste) are universally disliked:
+- **Hue range**: 50-120° (yellow-green)
+- **Chroma**: 20-50
+- **Tone**: 20-50
+
+#### Automatic Fixing
+```javascript
+if (isDisliked(color)) {
+  // Shift hue away from dislike zone
+  color.hue = adjustHue(color.hue);
+  // Increase tone for lighter appearance
+  color.tone = Math.max(60, color.tone);
+}
+```
+
+### Multi-Region Analysis
+
+For complex images, analyze different regions:
+
+```javascript
+// Analyze specific image regions
+const regions = [
+  { x: 0, y: 0, width: 100, height: 100 },    // Top-left
+  { x: 100, y: 100, width: 200, height: 200 } // Center
+];
+
+regions.forEach(region => {
+  const colors = extractFromRegion(image, region);
+  // Process regional colors
+});
+```
+
+### Temporal Consistency
+
+For video or animated content:
+
+```javascript
+// Extract colors from multiple frames
+const frames = [0, 30, 60, 90, 120];
+const frameColors = frames.map(f => extractFrame(video, f));
+
+// Find consistent colors across frames
+const stableColors = findStableColors(frameColors);
+```
+
+## Color Suitability Scoring
+
+### UI Suitability Factors
+
+| Factor | Weight | Description |
+|--------|--------|-------------|
+| Chroma | 40% | Preference for moderate chroma (~48) |
+| Population | 30% | How much of image uses this color |
+| Diversity | 20% | Distinctness from other colors |
+| Accessibility | 10% | Potential for good contrast |
+
+### Scoring Algorithm
+
+```javascript
+function scoreColor(color, population, existingColors) {
+  const chromaScore = scoreChroma(color.chroma);
+  const popScore = population / totalPopulation;
+  const diversityScore = scoreDiversity(color, existingColors);
+  const accessScore = scoreAccessibility(color);
+
+  return (
+    chromaScore * 0.4 +
+    popScore * 0.3 +
+    diversityScore * 0.2 +
+    accessScore * 0.1
+  );
+}
+```
+
+## Best Practices
+
+### Image Preparation
+
+#### Optimal Images
+- **Resolution**: 200-500px wide (resize larger images)
+- **Format**: RGB/RGBA
+- **Quality**: Avoid heavily compressed images
+- **Content**: Clear subject with distinct colors
+
+#### Pre-processing
+```javascript
+// Resize for performance
+const resized = resizeImage(original, 300);
+
+// Enhance contrast if needed
+const enhanced = enhanceContrast(resized, 1.2);
+
+// Extract colors
+const colors = extractColors(enhanced);
+```
+
+### Performance Optimization
+
+#### Sampling Strategies
+```javascript
+// Fast: Sample every 5th pixel
+const fastColors = quantize(pixels, 128, { sampling: 5 });
+
+// Quality: Full pixel analysis
+const qualityColors = quantize(pixels, 128, { sampling: 1 });
+
+// Adaptive: Based on image size
+const sampling = pixels.length > 100000 ? 5 : 1;
+```
+
+#### Caching
+```javascript
+// Cache extracted colors
+const cache = new Map();
+const hash = hashImage(imageData);
+
+if (cache.has(hash)) {
+  return cache.get(hash);
+}
+
+const colors = extractColors(imageData);
+cache.set(hash, colors);
+```
+
+## Use Cases
+
+### Dynamic Theming
+Apps that adapt to content:
+- Music players matching album art
+- News readers matching article images
+- Photo galleries with ambient themes
+
+### Brand Extraction
+Deriving brand colors from logos:
+```javascript
+const logo = loadImage('logo.png');
+const brandColors = extractColors(logo, {
+  maxColors: 3,
+  minChroma: 30  // Ensure vibrant colors
+});
+```
+
+### Palette Generation
+Creating artist palettes from artwork:
+```javascript
+const artwork = loadImage('painting.jpg');
+const palette = extractColors(artwork, {
+  maxColors: 12,
+  includeNeutrals: true
+});
+```
+
+## Integration Examples
+
+### Web Applications
+
+```javascript
+// Extract colors from uploaded image
+async function themeFromUpload(file) {
+  const image = await loadImage(file);
+  const canvas = createCanvas(image);
+  const pixels = getPixelData(canvas);
+
+  const response = await coolorsMCP.extractColors({
+    imageData: pixels,
+    maxColors: 5
+  });
+
+  return response.colors[0]; // Use top color
+}
+```
+
+### React Component
+
+```jsx
+function ImageThemeProvider({ imageUrl, children }) {
+  const [theme, setTheme] = useState(null);
+
+  useEffect(() => {
+    extractThemeFromImage(imageUrl).then(setTheme);
+  }, [imageUrl]);
+
+  return (
+    <ThemeContext.Provider value={theme}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+```
+
+### Node.js Server
+
+```javascript
+const sharp = require('sharp');
+
+async function extractFromBuffer(buffer) {
+  // Resize and convert to raw pixels
+  const { data, info } = await sharp(buffer)
+    .resize(300)
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+
+  // Extract colors
+  const colors = await coolorsMCP.extractColors({
+    imageData: Array.from(data),
+    width: info.width,
+    height: info.height
+  });
+
+  return colors;
+}
+```
+
+## Limitations
+
+### Technical Constraints
+- Maximum image size: ~5MB recommended
+- Color count: 128 colors maximum per extraction
+- Processing time: ~100-500ms for typical images
+
+### Accuracy Considerations
+- Compressed images may lose color fidelity
+- Very dark/light images provide limited options
+- Monochrome images need fallback strategies
+
+## Troubleshooting
+
+### Common Issues
+
+#### No Suitable Colors Found
+**Cause**: Image too monochrome or low contrast
+**Solution**: Adjust scoring thresholds or provide fallback
+
+#### Inconsistent Results
+**Cause**: Image compression or resizing artifacts
+**Solution**: Use higher quality source images
+
+#### Performance Problems
+**Cause**: Processing large images
+**Solution**: Resize before extraction
+
+## See Also
+
+- [Material Design](./material-design.md) - Theme generation from colors
+- [Color Spaces](./color-spaces.md) - Understanding color models
+- [HCT System](./hct.md) - Perceptual color space
+- [Accessibility](./accessibility.md) - Ensuring extracted colors are usable