@trishchuk/coolors-mcp 1.0.0 → 1.1.0

package/docs/tools/accessibility.md

@@ -8,36 +8,36 @@ Check the contrast ratio between two colors and verify WCAG compliance.
 
 ### Parameters
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `foreground` | string | ✅ | Foreground/text color (hex, rgb, hsl) |
-| `background` | string | ✅ | Background color (hex, rgb, hsl) |
-| `fontSize` | number | ❌ | Font size in pixels (for determining large text) |
-| `fontWeight` | number | ❌ | Font weight (for determining bold text) |
+| Parameter    | Type   | Required | Description                                      |
+| ------------ | ------ | -------- | ------------------------------------------------ |
+| `foreground` | string | ✅       | Foreground/text color (hex, rgb, hsl)            |
+| `background` | string | ✅       | Background color (hex, rgb, hsl)                 |
+| `fontSize`   | number | ❌       | Font size in pixels (for determining large text) |
+| `fontWeight` | number | ❌       | Font weight (for determining bold text)          |
 
 ### Returns
 
 ```typescript
 {
-  ratio: number;          // Contrast ratio (1-21)
-  ratioString: string;    // Formatted as "X.XX:1"
+  ratio: number; // Contrast ratio (1-21)
+  ratioString: string; // Formatted as "X.XX:1"
   passes: {
     AA: {
-      normal: boolean;    // Passes AA for normal text (4.5:1)
-      large: boolean;     // Passes AA for large text (3:1)
-      nonText: boolean;   // Passes AA for UI elements (3:1)
-    };
+      normal: boolean; // Passes AA for normal text (4.5:1)
+      large: boolean; // Passes AA for large text (3:1)
+      nonText: boolean; // Passes AA for UI elements (3:1)
+    }
     AAA: {
-      normal: boolean;    // Passes AAA for normal text (7:1)
-      large: boolean;     // Passes AAA for large text (4.5:1)
+      normal: boolean; // Passes AAA for normal text (7:1)
+      large: boolean; // Passes AAA for large text (4.5:1)
     }
-  };
+  }
   recommendation: string; // Human-readable recommendation
   luminance: {
-    foreground: number;   // Relative luminance (0-1)
-    background: number;   // Relative luminance (0-1)
-  };
-  isLargeText: boolean;  // Whether text qualifies as large
+    foreground: number; // Relative luminance (0-1)
+    background: number; // Relative luminance (0-1)
+  }
+  isLargeText: boolean; // Whether text qualifies as large
 }
 ```
 
@@ -113,9 +113,9 @@ Check the contrast ratio between two colors and verify WCAG compliance.
 ```javascript
 // Test color pairs
 const pairs = [
-  { fg: "#1f2937", bg: "#ffffff" },  // Dark gray on white
-  { fg: "#6366f1", bg: "#f3f4f6" },  // Blue on light gray
-  { fg: "#ffffff", bg: "#dc2626" }   // White on red
+  { fg: "#1f2937", bg: "#ffffff" }, // Dark gray on white
+  { fg: "#6366f1", bg: "#f3f4f6" }, // Blue on light gray
+  { fg: "#ffffff", bg: "#dc2626" }, // White on red
 ];
 
 for (const pair of pairs) {
@@ -127,6 +127,7 @@ for (const pair of pairs) {
 ### Large Text Definition
 
 Text is considered "large" when:
+
 - Font size ≥ 18pt (24px)
 - Font size ≥ 14pt (18.67px) AND bold (weight ≥ 700)
 
@@ -143,12 +144,12 @@ Automatically adjust a color to meet contrast requirements.
 
 ### Parameters
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `foreground` | string | ✅ | Color to adjust |
-| `background` | string | ✅ | Background color |
-| `targetRatio` | number | ✅ | Minimum contrast ratio needed |
-| `preferLighter` | boolean | ❌ | Prefer lightening over darkening |
+| Parameter       | Type    | Required | Description                      |
+| --------------- | ------- | -------- | -------------------------------- |
+| `foreground`    | string  | ✅       | Color to adjust                  |
+| `background`    | string  | ✅       | Background color                 |
+| `targetRatio`   | number  | ✅       | Minimum contrast ratio needed    |
+| `preferLighter` | boolean | ❌       | Prefer lightening over darkening |
 
 ### Returns
 
@@ -157,14 +158,14 @@ Automatically adjust a color to meet contrast requirements.
   original: {
     color: string;
     ratio: number;
-  };
+  }
   adjusted: {
     color: string;
     ratio: number;
-  };
+  }
   adjustmentMade: boolean;
-  adjustmentType: 'lightened' | 'darkened' | 'none';
-  toneChange: number;     // HCT tone difference
+  adjustmentType: "lightened" | "darkened" | "none";
+  toneChange: number; // HCT tone difference
 }
 ```
 
@@ -241,12 +242,12 @@ Generate accessible color pairs for different UI contexts.
 
 ### Parameters
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `baseColor` | string | ✅ | Starting color |
-| `count` | number | ❌ | Number of pairs to generate (default: 5) |
-| `contrastLevels` | string[] | ❌ | Required levels: AA, AAA (default: ['AA']) |
-| `contexts` | string[] | ❌ | UI contexts: text, button, border (default: all) |
+| Parameter        | Type     | Required | Description                                      |
+| ---------------- | -------- | -------- | ------------------------------------------------ |
+| `baseColor`      | string   | ✅       | Starting color                                   |
+| `count`          | number   | ❌       | Number of pairs to generate (default: 5)         |
+| `contrastLevels` | string[] | ❌       | Required levels: AA, AAA (default: ['AA'])       |
+| `contexts`       | string[] | ❌       | UI contexts: text, button, border (default: all) |
 
 ### Returns
 
@@ -328,11 +329,11 @@ Check all color combinations in a palette for accessibility.
 
 ### Parameters
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `palette` | object | ✅ | Color palette with role names and values |
-| `level` | string | ❌ | WCAG level to test: AA, AAA (default: AA) |
-| `includeReport` | boolean | ❌ | Generate detailed report (default: true) |
+| Parameter       | Type    | Required | Description                               |
+| --------------- | ------- | -------- | ----------------------------------------- |
+| `palette`       | object  | ✅       | Color palette with role names and values  |
+| `level`         | string  | ❌       | WCAG level to test: AA, AAA (default: AA) |
+| `includeReport` | boolean | ❌       | Generate detailed report (default: true)  |
 
 ### Returns
 
@@ -432,19 +433,21 @@ Check all color combinations in a palette for accessibility.
 ### Contrast Requirements
 
 #### Text Content
-| Context | AA Minimum | AAA Minimum |
-|---------|------------|-------------|
-| Normal text | 4.5:1 | 7:1 |
-| Large text | 3:1 | 4.5:1 |
+
+| Context         | AA Minimum     | AAA Minimum    |
+| --------------- | -------------- | -------------- |
+| Normal text     | 4.5:1          | 7:1            |
+| Large text      | 3:1            | 4.5:1          |
 | Incidental text | No requirement | No requirement |
-| Logotypes | No requirement | No requirement |
+| Logotypes       | No requirement | No requirement |
 
 #### Non-Text Content
-| Context | AA Minimum | Notes |
-|---------|------------|-------|
-| UI components | 3:1 | Active components |
-| Graphics | 3:1 | Essential graphics |
-| Decorative | No requirement | Purely decorative |
+
+| Context       | AA Minimum     | Notes              |
+| ------------- | -------------- | ------------------ |
+| UI components | 3:1            | Active components  |
+| Graphics      | 3:1            | Essential graphics |
+| Decorative    | No requirement | Purely decorative  |
 
 ### Testing Strategy
 
@@ -454,7 +457,7 @@ async function testAccessibility(theme) {
   // 1. Check individual pairs
   const criticalPairs = [
     { fg: theme.text, bg: theme.background },
-    { fg: theme.primary, bg: theme.surface }
+    { fg: theme.primary, bg: theme.surface },
   ];
 
   for (const pair of criticalPairs) {
@@ -467,7 +470,7 @@ async function testAccessibility(theme) {
   // 2. Validate entire palette
   const validation = await validatePalette(theme);
   if (!validation.valid) {
-    console.error('Palette has accessibility issues:', validation.issues);
+    console.error("Palette has accessibility issues:", validation.issues);
   }
 
   // 3. Generate report
@@ -486,14 +489,14 @@ async function fixAccessibility(theme) {
   fixed.text = await ensureContrast({
     foreground: theme.text,
     background: theme.background,
-    targetRatio: 4.5
+    targetRatio: 4.5,
   });
 
   // Ensure buttons are accessible
   fixed.buttonText = await ensureContrast({
     foreground: theme.buttonText,
     background: theme.buttonBg,
-    targetRatio: 4.5
+    targetRatio: 4.5,
   });
 
   return fixed;
@@ -512,17 +515,17 @@ function validateDarkMode(darkTheme) {
     {
       fg: darkTheme.text,
       bg: darkTheme.background,
-      min: 4.5
+      min: 4.5,
     },
     // But not too harsh (avoid pure white on black)
     {
       fg: darkTheme.text,
       bg: darkTheme.background,
-      max: 18  // Avoid excessive contrast
-    }
+      max: 18, // Avoid excessive contrast
+    },
   ];
 
-  return checks.every(check => {
+  return checks.every((check) => {
     const ratio = getContrast(check.fg, check.bg);
     return ratio >= (check.min || 0) && ratio <= (check.max || 21);
   });
@@ -546,10 +549,10 @@ function generateContrastLevels(baseTheme) {
 
     // Maximum - For accessibility needs
     maximum: {
-      text: '#000000',
-      background: '#ffffff',
-      primary: '#0000ff'
-    }
+      text: "#000000",
+      background: "#ffffff",
+      primary: "#0000ff",
+    },
   };
 }
 ```
@@ -570,12 +573,12 @@ function validateFormColors(formTheme) {
     focusRing: { min: 3.0, against: formTheme.inputBg },
 
     // Placeholder text (relaxed requirement)
-    placeholder: { min: 3.0, against: formTheme.inputBg }
+    placeholder: { min: 3.0, against: formTheme.inputBg },
   };
 
   return Object.entries(requirements).map(([element, req]) => ({
     element,
-    passes: checkContrast(formTheme[element], req.against).ratio >= req.min
+    passes: checkContrast(formTheme[element], req.against).ratio >= req.min,
   }));
 }
 ```
@@ -586,6 +589,7 @@ function validateFormColors(formTheme) {
 
 **Problem**: Colors don't meet minimum contrast
 **Solution**:
+
 - Use `ensure_contrast` to auto-adjust
 - Increase tone difference between colors
 - Consider different color roles
@@ -594,6 +598,7 @@ function validateFormColors(formTheme) {
 
 **Problem**: Maximum contrast (21:1) is too harsh
 **Solution**:
+
 - Use off-white (#fafafa) instead of pure white
 - Use very dark gray (#0a0a0a) instead of pure black
 - Aim for 12-15:1 for comfortable reading
@@ -602,6 +607,7 @@ function validateFormColors(formTheme) {
 
 **Problem**: Adjusted colors lose brand identity
 **Solution**:
+
 - Adjust the background instead of foreground
 - Use borders or icons to supplement color
 - Provide high-contrast mode as option
@@ -611,4 +617,4 @@ function validateFormColors(formTheme) {
 - [Accessibility Concepts](../concepts/accessibility.md) - WCAG standards explained
 - [HCT System](../concepts/hct.md) - Tone-based contrast
 - [Color Operations](./color-operations.md) - Color manipulation
-- [Material Design Tools](./material-design.md) - Accessible themes
+- [Material Design Tools](./material-design.md) - Accessible themes

package/docs/tools/image-extraction.md

@@ -8,27 +8,28 @@ Extract dominant colors from an image using Google's Celebi quantization algorit
 
 ### Parameters
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `imageData` | number[] | ✅ | RGBA pixel array (flat array of values 0-255) |
-| `maxColors` | number | ❌ | Maximum colors to extract (default: 5, max: 128) |
-| `minPopulation` | number | ❌ | Minimum pixel percentage for color (default: 0.01) |
-| `targetChroma` | number | ❌ | Preferred chroma for UI colors (default: 48) |
+| Parameter       | Type     | Required | Description                                        |
+| --------------- | -------- | -------- | -------------------------------------------------- |
+| `imageData`     | number[] | ✅       | RGBA pixel array (flat array of values 0-255)      |
+| `maxColors`     | number   | ❌       | Maximum colors to extract (default: 5, max: 128)   |
+| `minPopulation` | number   | ❌       | Minimum pixel percentage for color (default: 0.01) |
+| `targetChroma`  | number   | ❌       | Preferred chroma for UI colors (default: 48)       |
 
 ### Returns
 
 ```typescript
 {
   colors: Array<{
-    hex: string;         // Hex color value
-    rgb: [r, g, b];     // RGB values
-    hct: {              // HCT values
+    hex: string; // Hex color value
+    rgb: [r, g, b]; // RGB values
+    hct: {
+      // HCT values
       hue: number;
       chroma: number;
       tone: number;
     };
-    population: number;  // Percentage of image (0-1)
-    score: number;      // UI suitability score (0-1)
+    population: number; // Percentage of image (0-1)
+    score: number; // UI suitability score (0-1)
   }>;
   metadata: {
     totalPixels: number;
@@ -111,8 +112,8 @@ Extract dominant colors from an image using Google's Celebi quantization algorit
 #### From Canvas (Browser)
 
 ```javascript
-const canvas = document.getElementById('canvas');
-const ctx = canvas.getContext('2d');
+const canvas = document.getElementById("canvas");
+const ctx = canvas.getContext("2d");
 const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
 
 // Convert to flat array
@@ -120,25 +121,25 @@ const pixels = Array.from(imageData.data);
 
 // Extract colors
 const result = await extractColors({
-  imageData: pixels
+  imageData: pixels,
 });
 ```
 
 #### From Image File (Node.js)
 
 ```javascript
-const sharp = require('sharp');
+const sharp = require("sharp");
 
 async function getPixelsFromImage(filepath) {
   const { data, info } = await sharp(filepath)
-    .resize(300)  // Resize for performance
+    .resize(300) // Resize for performance
     .raw()
     .toBuffer({ resolveWithObject: true });
 
   return Array.from(data);
 }
 
-const pixels = await getPixelsFromImage('photo.jpg');
+const pixels = await getPixelsFromImage("photo.jpg");
 ```
 
 ### Use Cases
@@ -154,18 +155,18 @@ Generate a complete Material Design 3 theme from an image.
 
 ### Parameters
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `imageData` | number[] | ✅ | RGBA pixel array |
-| `variant` | string | ❌ | Theme variant: tonalSpot, fidelity, vibrant, expressive, neutral, monochrome |
-| `contrastLevel` | number | ❌ | Contrast level: 0 (default), 0.5 (medium), 1.0 (high) |
-| `sourceColorIndex` | number | ❌ | Which extracted color to use as source (default: 0) |
+| Parameter          | Type     | Required | Description                                                                  |
+| ------------------ | -------- | -------- | ---------------------------------------------------------------------------- |
+| `imageData`        | number[] | ✅       | RGBA pixel array                                                             |
+| `variant`          | string   | ❌       | Theme variant: tonalSpot, fidelity, vibrant, expressive, neutral, monochrome |
+| `contrastLevel`    | number   | ❌       | Contrast level: 0 (default), 0.5 (medium), 1.0 (high)                        |
+| `sourceColorIndex` | number   | ❌       | Which extracted color to use as source (default: 0)                          |
 
 ### Returns
 
 ```typescript
 {
-  sourceColor: string;   // Selected source color
+  sourceColor: string; // Selected source color
   extractedColors: Array<{
     hex: string;
     score: number;
@@ -178,19 +179,19 @@ Generate a complete Material Design 3 theme from an image.
       primaryContainer: string;
       onPrimaryContainer: string;
       // ... all Material Design color roles
-    };
+    }
     dark: {
       // ... dark theme colors
     }
-  };
+  }
   palettes: {
     primary: object;
     secondary: object;
     tertiary: object;
     neutral: object;
     error: object;
-  };
-  css: string;  // Generated CSS variables
+  }
+  css: string; // Generated CSS variables
 }
 ```
 
@@ -268,14 +269,14 @@ Generate a complete Material Design 3 theme from an image.
 
 ### Theme Variants
 
-| Variant | Description | Best For |
-|---------|-------------|----------|
-| `tonalSpot` | Default, balanced | General use |
-| `fidelity` | Preserves source color | Brand-critical |
-| `vibrant` | Higher chroma | Playful, energetic |
+| Variant      | Description             | Best For           |
+| ------------ | ----------------------- | ------------------ |
+| `tonalSpot`  | Default, balanced       | General use        |
+| `fidelity`   | Preserves source color  | Brand-critical     |
+| `vibrant`    | Higher chroma           | Playful, energetic |
 | `expressive` | Unexpected combinations | Creative, artistic |
-| `neutral` | Minimal color | Professional |
-| `monochrome` | Single hue | Minimalist |
+| `neutral`    | Minimal color           | Professional       |
+| `monochrome` | Single hue              | Minimalist         |
 
 ### Use Cases
 
@@ -290,10 +291,10 @@ Check if a color falls in the universally disliked "bile zone" and get a fixed v
 
 ### Parameters
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `color` | string | ✅ | Color to analyze (hex, rgb, hsl) |
-| `autoFix` | boolean | ❌ | Automatically return fixed version (default: true) |
+| Parameter | Type    | Required | Description                                        |
+| --------- | ------- | -------- | -------------------------------------------------- |
+| `color`   | string  | ✅       | Color to analyze (hex, rgb, hsl)                   |
+| `autoFix` | boolean | ❌       | Automatically return fixed version (default: true) |
 
 ### Returns
 
@@ -358,6 +359,7 @@ Check if a color falls in the universally disliked "bile zone" and get a fixed v
 ### The Dislike Zone
 
 Colors are universally disliked when they have:
+
 - **Hue**: 50-120° (yellow-green range)
 - **Chroma**: 20-50 (moderate saturation)
 - **Tone**: 20-50 (dark to medium)
@@ -377,10 +379,10 @@ Analyze and fix multiple colors, returning only liked versions.
 
 ### Parameters
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `colors` | string[] | ✅ | Array of colors to check |
-| `strategy` | string | ❌ | Fix strategy: shift, lighten, both (default: both) |
+| Parameter  | Type     | Required | Description                                        |
+| ---------- | -------- | -------- | -------------------------------------------------- |
+| `colors`   | string[] | ✅       | Array of colors to check                           |
+| `strategy` | string   | ❌       | Fix strategy: shift, lighten, both (default: both) |
 
 ### Returns
 
@@ -466,6 +468,7 @@ Analyze and fix multiple colors, returning only liked versions.
 ### Image Preparation
 
 #### Optimal Size
+
 - Resize images to 200-500px width
 - Larger images don't improve accuracy
 - Smaller images process faster
@@ -473,11 +476,12 @@ Analyze and fix multiple colors, returning only liked versions.
 ```javascript
 // Resize before extraction
 const resized = await sharp(image)
-  .resize(300, null, { fit: 'inside' })
+  .resize(300, null, { fit: "inside" })
   .toBuffer();
 ```
 
 #### Image Quality
+
 - Use uncompressed or lightly compressed images
 - Avoid heavily filtered images
 - Ensure good color representation
@@ -505,19 +509,19 @@ function getCachedColors(imageHash) {
 ```javascript
 // Process multiple images efficiently
 const images = [img1, img2, img3];
-const results = await Promise.all(
-  images.map(img => extractColors(img))
-);
+const results = await Promise.all(images.map((img) => extractColors(img)));
 ```
 
 ### Color Selection
 
 #### For UI Themes
+
 - Prefer colors with chroma 40-60
 - Avoid very dark or very light colors
 - Check for accessibility
 
 #### For Artistic Palettes
+
 - Include wider chroma range
 - Keep accent colors
 - Preserve unique hues
@@ -534,11 +538,11 @@ async function themeFromAlbumArt(artworkUrl) {
   // 2. Generate theme
   const theme = await generateThemeFromImage({
     imageData: pixels,
-    variant: 'vibrant'  // Music apps often use vibrant themes
+    variant: "vibrant", // Music apps often use vibrant themes
   });
 
   // 3. Apply to UI
-  applyTheme(theme.schemes.dark);  // Music apps often use dark themes
+  applyTheme(theme.schemes.dark); // Music apps often use dark themes
 }
 ```
 
@@ -552,8 +556,8 @@ async function extractBrandColors(logoPath) {
   // 2. Extract colors
   const extracted = await extractColors({
     imageData: pixels,
-    maxColors: 3,  // Logos typically have few colors
-    minPopulation: 0.05  // Higher threshold for logos
+    maxColors: 3, // Logos typically have few colors
+    minPopulation: 0.05, // Higher threshold for logos
   });
 
   // 3. Fix any disliked colors
@@ -574,8 +578,8 @@ async function adaptiveBackground(imageUrl) {
   // 2. Create subtle background
   const background = {
     ...dominant.hct,
-    chroma: dominant.hct.chroma * 0.3,  // Reduce chroma
-    tone: 95  // Very light
+    chroma: dominant.hct.chroma * 0.3, // Reduce chroma
+    tone: 95, // Very light
   };
 
   return hctToHex(background);
@@ -588,6 +592,7 @@ async function adaptiveBackground(imageUrl) {
 
 **Problem**: Empty result from extraction
 **Solution**:
+
 - Check image data format (must be RGBA)
 - Verify pixel array is not empty
 - Lower minPopulation threshold
@@ -596,6 +601,7 @@ async function adaptiveBackground(imageUrl) {
 
 **Problem**: Extracted colors don't represent image well
 **Solution**:
+
 - Increase maxColors
 - Adjust targetChroma for different types
 - Try different quantization settings
@@ -604,6 +610,7 @@ async function adaptiveBackground(imageUrl) {
 
 **Problem**: Extracted colors are unpleasant
 **Solution**:
+
 - Use `fix_disliked_colors_batch`
 - Adjust extraction to avoid bile zone
 - Post-process results
@@ -612,6 +619,7 @@ async function adaptiveBackground(imageUrl) {
 
 **Problem**: Slow extraction for large images
 **Solution**:
+
 - Resize images before extraction
 - Use sampling (process every nth pixel)
 - Cache results for repeated images
@@ -621,4 +629,4 @@ async function adaptiveBackground(imageUrl) {
 - [Image Analysis Concepts](../concepts/image-analysis.md) - How extraction works
 - [Material Design Tools](./material-design.md) - Theme generation
 - [Color Operations](./color-operations.md) - Color manipulation
-- [Image Extraction Examples](../examples/image-extraction.md) - Practical examples
+- [Image Extraction Examples](../examples/image-extraction.md) - Practical examples