@trishchuk/coolors-mcp 1.0.0 → 1.1.0

package/docs/concepts/image-analysis.md

@@ -5,6 +5,7 @@ Coolors MCP provides advanced image color extraction using Google's Material Col
 ## 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
@@ -17,7 +18,9 @@ Image color extraction involves:
 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
 
@@ -27,6 +30,7 @@ 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
@@ -40,24 +44,29 @@ Not all colors are suitable for UI themes. The scoring algorithm evaluates color
 
 **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)
@@ -78,20 +87,26 @@ The system selects multiple source colors for theme options:
 ## 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
@@ -147,12 +162,15 @@ Personal photos for custom themes:
 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
@@ -169,11 +187,11 @@ 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
+  { x: 0, y: 0, width: 100, height: 100 }, // Top-left
+  { x: 100, y: 100, width: 200, height: 200 }, // Center
 ];
 
-regions.forEach(region => {
+regions.forEach((region) => {
   const colors = extractFromRegion(image, region);
   // Process regional colors
 });
@@ -186,7 +204,7 @@ 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));
+const frameColors = frames.map((f) => extractFrame(video, f));
 
 // Find consistent colors across frames
 const stableColors = findStableColors(frameColors);
@@ -196,12 +214,12 @@ const stableColors = findStableColors(frameColors);
 
 ### 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 |
+| 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
 
@@ -226,12 +244,14 @@ function scoreColor(color, population, existingColors) {
 ### 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);
@@ -246,6 +266,7 @@ const colors = extractColors(enhanced);
 ### Performance Optimization
 
 #### Sampling Strategies
+
 ```javascript
 // Fast: Sample every 5th pixel
 const fastColors = quantize(pixels, 128, { sampling: 5 });
@@ -258,6 +279,7 @@ const sampling = pixels.length > 100000 ? 5 : 1;
 ```
 
 #### Caching
+
 ```javascript
 // Cache extracted colors
 const cache = new Map();
@@ -274,28 +296,34 @@ 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 logo = loadImage("logo.png");
 const brandColors = extractColors(logo, {
   maxColors: 3,
-  minChroma: 30  // Ensure vibrant colors
+  minChroma: 30, // Ensure vibrant colors
 });
 ```
 
 ### Palette Generation
+
 Creating artist palettes from artwork:
+
 ```javascript
-const artwork = loadImage('painting.jpg');
+const artwork = loadImage("painting.jpg");
 const palette = extractColors(artwork, {
   maxColors: 12,
-  includeNeutrals: true
+  includeNeutrals: true,
 });
 ```
 
@@ -312,7 +340,7 @@ async function themeFromUpload(file) {
 
   const response = await coolorsMCP.extractColors({
     imageData: pixels,
-    maxColors: 5
+    maxColors: 5,
   });
 
   return response.colors[0]; // Use top color
@@ -330,9 +358,7 @@ function ImageThemeProvider({ imageUrl, children }) {
   }, [imageUrl]);
 
   return (
-    <ThemeContext.Provider value={theme}>
-      {children}
-    </ThemeContext.Provider>
+    <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>
   );
 }
 ```
@@ -340,7 +366,7 @@ function ImageThemeProvider({ imageUrl, children }) {
 ### Node.js Server
 
 ```javascript
-const sharp = require('sharp');
+const sharp = require("sharp");
 
 async function extractFromBuffer(buffer) {
   // Resize and convert to raw pixels
@@ -353,7 +379,7 @@ async function extractFromBuffer(buffer) {
   const colors = await coolorsMCP.extractColors({
     imageData: Array.from(data),
     width: info.width,
-    height: info.height
+    height: info.height,
   });
 
   return colors;
@@ -363,11 +389,13 @@ async function extractFromBuffer(buffer) {
 ## 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
@@ -377,14 +405,17 @@ async function extractFromBuffer(buffer) {
 ### 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
 
@@ -393,4 +424,4 @@ async function extractFromBuffer(buffer) {
 - [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
+- [Accessibility](./accessibility.md) - Ensuring extracted colors are usable

package/docs/concepts/material-design.md

@@ -15,30 +15,35 @@ Dynamic color is the heart of Material Design 3, enabling personalized experienc
 Material Design 3 defines semantic color roles that map to UI elements consistently:
 
 ### Primary Colors
+
 - **primary**: Main brand or theme color (tone 40 in light, 80 in dark)
 - **onPrimary**: Text/icons on primary color (tone 100 in light, 20 in dark)
 - **primaryContainer**: Light container variant (tone 90 in light, 30 in dark)
 - **onPrimaryContainer**: Text on primary container (tone 10 in light, 90 in dark)
 
 ### Secondary Colors
+
 - **secondary**: Supporting brand color
 - **onSecondary**: Text/icons on secondary
 - **secondaryContainer**: Light container variant
 - **onSecondaryContainer**: Text on secondary container
 
 ### Tertiary Colors
+
 - **tertiary**: Accent for special emphasis
 - **onTertiary**: Text/icons on tertiary
 - **tertiaryContainer**: Light container variant
 - **onTertiaryContainer**: Text on tertiary container
 
 ### Surface Colors
+
 - **surface**: Main background color (tone 99 in light, 10 in dark)
 - **onSurface**: Primary text color (tone 10 in light, 90 in dark)
 - **surfaceVariant**: Secondary background (tone 95 in light, 30 in dark)
 - **onSurfaceVariant**: Secondary text (tone 30 in light, 80 in dark)
 
 ### Additional Roles
+
 - **error**: Error states (hue ~25, chroma 84)
 - **outline**: Borders and dividers
 - **shadow**: Shadow colors
@@ -57,13 +62,13 @@ Material Design 3 uses 13 standard tones for each color palette:
 
 ### Tone Usage Guidelines
 
-| Tone Range | Light Theme Usage | Dark Theme Usage |
-|------------|------------------|------------------|
-| 0-10 | On-colors, high emphasis text | Surfaces, containers |
-| 20-40 | Primary actions, emphasis | On-colors, text |
-| 50 | Neutral midpoint | Neutral midpoint |
-| 60-80 | Containers, surfaces | Primary actions |
-| 90-100 | Backgrounds, surfaces | On-colors, text |
+| Tone Range | Light Theme Usage             | Dark Theme Usage     |
+| ---------- | ----------------------------- | -------------------- |
+| 0-10       | On-colors, high emphasis text | Surfaces, containers |
+| 20-40      | Primary actions, emphasis     | On-colors, text      |
+| 50         | Neutral midpoint              | Neutral midpoint     |
+| 60-80      | Containers, surfaces          | Primary actions      |
+| 90-100     | Backgrounds, surfaces         | On-colors, text      |
 
 ## Key Colors
 
@@ -80,31 +85,37 @@ From a single source color, Material Design generates five key colors:
 Material Design 3 offers multiple scheme variants for different moods:
 
 ### Tonal Spot (Default)
+
 - Balanced use of primary color
 - Secondary and tertiary are complementary
 - Most versatile for general use
 
 ### Fidelity
+
 - Preserves source color's exact appearance
 - Adjusts tones to maintain chroma
 - Best for brand-critical applications
 
 ### Vibrant
+
 - Higher chroma across all colors
 - More colorful, energetic appearance
 - Good for creative, playful apps
 
 ### Expressive
+
 - Unexpected color combinations
 - Creative hue rotations
 - For bold, artistic interfaces
 
 ### Neutral
+
 - Minimal color, maximum elegance
 - Reduced chroma values
 - Professional, understated look
 
 ### Monochrome
+
 - Single hue, varying tones
 - Ultimate minimalism
 - Focus on content over color
@@ -114,16 +125,19 @@ Material Design 3 offers multiple scheme variants for different moods:
 Material Design 3 supports three contrast levels:
 
 ### Default (0.0)
+
 - WCAG AA compliant
 - 4.5:1 for normal text
 - 3:1 for large text
 
 ### Medium (+0.5)
+
 - Enhanced readability
 - ~6:1 for normal text
 - Better for outdoor/bright conditions
 
 ### High (+1.0)
+
 - WCAG AAA compliant
 - 7:1 for normal text
 - Maximum accessibility
@@ -173,12 +187,14 @@ Material Design 3 supports three contrast levels:
 Material Design uses harmonization to ensure colors work together:
 
 ### Harmonization Algorithm
+
 1. Analyze hue relationships
 2. Adjust hues toward harmony angles (0°, 60°, 120°, 180°, 240°, 300°)
 3. Maintain original chroma and tone
 4. Blend based on harmonization strength
 
 ### Example
+
 ```javascript
 {
   "name": "harmonize_colors",
@@ -194,11 +210,12 @@ Material Design uses harmonization to ensure colors work together:
 Material Design 3 uses design tokens for consistent application:
 
 ### Token Structure
+
 ```css
 /* Color tokens */
---md-sys-color-primary: #6366F1;
---md-sys-color-on-primary: #FFFFFF;
---md-sys-color-primary-container: #E0E2FF;
+--md-sys-color-primary: #6366f1;
+--md-sys-color-on-primary: #ffffff;
+--md-sys-color-primary-container: #e0e2ff;
 --md-sys-color-on-primary-container: #000747;
 
 /* Elevation tokens */
@@ -236,6 +253,7 @@ The complete process for generating a Material theme:
 ## Best Practices
 
 ### Do's
+
 - ✅ Use semantic color roles consistently
 - ✅ Test with all three contrast levels
 - ✅ Validate color combinations for accessibility
@@ -243,6 +261,7 @@ The complete process for generating a Material theme:
 - ✅ Use harmonization for multiple brand colors
 
 ### Don'ts
+
 - ❌ Override tone assignments arbitrarily
 - ❌ Use colors outside the tonal palettes
 - ❌ Ignore contrast requirements
@@ -252,6 +271,7 @@ The complete process for generating a Material theme:
 ## Integration Examples
 
 ### React/CSS
+
 ```css
 :root {
   --md-sys-color-primary: rgb(99, 102, 241);
@@ -265,33 +285,39 @@ The complete process for generating a Material theme:
 ```
 
 ### Tailwind CSS
+
 ```javascript
 // tailwind.config.js
 module.exports = {
   theme: {
     extend: {
       colors: {
-        'md-primary': 'var(--md-sys-color-primary)',
-        'md-surface': 'var(--md-sys-color-surface)',
-      }
-    }
-  }
-}
+        "md-primary": "var(--md-sys-color-primary)",
+        "md-surface": "var(--md-sys-color-surface)",
+      },
+    },
+  },
+};
 ```
 
 ## Advanced Features
 
 ### Dislike Prevention
+
 Material Design automatically detects and adjusts universally disliked colors (dark yellow-greens that resemble biological waste) by shifting their hue and increasing tone.
 
 ### Content-Based Schemes
+
 Generate schemes that adapt to content:
+
 - Album artwork → Music player theme
 - Product images → E-commerce theme
 - User photos → Gallery theme
 
 ### Cross-Platform Consistency
+
 The same source color produces identical themes across:
+
 - Android (Material You)
 - Web (Material Web)
 - Flutter
@@ -303,4 +329,4 @@ The same source color produces identical themes across:
 - [Color Spaces](./color-spaces.md) - Color space comparisons
 - [Accessibility](./accessibility.md) - Contrast and accessibility
 - [Image Analysis](./image-analysis.md) - Extracting colors from images
-- [Material Design Guidelines](https://m3.material.io) - Official documentation
+- [Material Design Guidelines](https://m3.material.io) - Official documentation