@trishchuk/coolors-mcp 1.0.0

package/docs/concepts/material-design.md

@@ -0,0 +1,306 @@
+# Material Design 3 Color System
+
+Material Design 3 introduces a revolutionary approach to color through dynamic color schemes that adapt to user preferences and content while maintaining accessibility and visual harmony.
+
+## Dynamic Color Overview
+
+Dynamic color is the heart of Material Design 3, enabling personalized experiences through:
+
+- **User-generated color**: Extracted from wallpapers or user preferences
+- **Content-based color**: Derived from app content like album art or logos
+- **Systematic generation**: Creating complete themes from a single source color
+
+## Color Roles
+
+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
+- **scrim**: Modal overlays
+- **inverseSurface**: Inverted surface for emphasis
+- **inverseOnSurface**: Text on inverted surface
+- **inversePrimary**: Primary color on inverted surface
+
+## Tonal Palettes
+
+Material Design 3 uses 13 standard tones for each color palette:
+
+```
+[0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100]
+```
+
+### 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 |
+
+## Key Colors
+
+From a single source color, Material Design generates five key colors:
+
+1. **Primary**: Directly from source color
+2. **Secondary**: Complementary color (hue shift ~60°, chroma × 0.5)
+3. **Tertiary**: Triadic color (hue shift ~120°, chroma × 0.7)
+4. **Error**: Standardized error color (hue 25, chroma 84)
+5. **Neutral**: Grayscale derived from source (chroma 4-8)
+
+## Scheme Variants
+
+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
+
+## Contrast Levels
+
+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
+
+## Implementation with Coolors MCP
+
+### Generate Material Theme
+
+```javascript
+// From a source color
+{
+  "name": "generate_material_theme",
+  "arguments": {
+    "sourceColor": "#6366F1"
+  }
+}
+```
+
+### Create Tonal Palette
+
+```javascript
+// Generate standard Material tones
+{
+  "name": "generate_tonal_palette",
+  "arguments": {
+    "color": "#6366F1",
+    "tones": [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100]
+  }
+}
+```
+
+### Generate Theme CSS
+
+```javascript
+// Create CSS custom properties
+{
+  "name": "generate_theme_css",
+  "arguments": {
+    "sourceColor": "#6366F1",
+    "prefix": "md"
+  }
+}
+```
+
+## Color Harmonization
+
+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",
+  "arguments": {
+    "colors": ["#6366F1", "#EC4899", "#10B981"],
+    "factor": 0.5
+  }
+}
+```
+
+## Design Tokens
+
+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-on-primary-container: #000747;
+
+/* Elevation tokens */
+--md-sys-elevation-level0: 0px;
+--md-sys-elevation-level1: 1px;
+--md-sys-elevation-level2: 3px;
+
+/* Shape tokens */
+--md-sys-shape-corner-small: 4px;
+--md-sys-shape-corner-medium: 8px;
+--md-sys-shape-corner-large: 16px;
+```
+
+## Accessibility Considerations
+
+Material Design 3 ensures accessibility through:
+
+1. **Guaranteed Contrast**: Tone relationships ensure WCAG compliance
+2. **Color Independence**: Information not conveyed by color alone
+3. **Predictable Patterns**: Consistent color role usage
+4. **Adjustable Contrast**: Support for user preferences
+
+## Dynamic Color Algorithm
+
+The complete process for generating a Material theme:
+
+1. **Extract source color** from image or user input
+2. **Generate key colors** through hue/chroma manipulation
+3. **Create tonal palettes** for each key color
+4. **Map tones to roles** based on scheme variant
+5. **Adjust for contrast** requirements
+6. **Apply fidelity corrections** if needed
+7. **Output theme** as usable color values
+
+## Best Practices
+
+### Do's
+- ✅ Use semantic color roles consistently
+- ✅ Test with all three contrast levels
+- ✅ Validate color combinations for accessibility
+- ✅ Consider both light and dark themes
+- ✅ Use harmonization for multiple brand colors
+
+### Don'ts
+- ❌ Override tone assignments arbitrarily
+- ❌ Use colors outside the tonal palettes
+- ❌ Ignore contrast requirements
+- ❌ Mix scheme variants in one interface
+- ❌ Use extreme chroma values for large surfaces
+
+## Integration Examples
+
+### React/CSS
+```css
+:root {
+  --md-sys-color-primary: rgb(99, 102, 241);
+  --md-sys-color-surface: rgb(252, 252, 255);
+}
+
+.button-primary {
+  background: var(--md-sys-color-primary);
+  color: var(--md-sys-color-on-primary);
+}
+```
+
+### 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)',
+      }
+    }
+  }
+}
+```
+
+## 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
+- Coolors MCP
+
+## See Also
+
+- [HCT Color System](./hct.md) - Understanding the HCT color space
+- [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

package/docs/concepts/theme-matching.md

@@ -0,0 +1,399 @@
+# Theme Matching Algorithm
+
+Coolors MCP provides sophisticated algorithms for matching colors to CSS theme variables, enabling automated refactoring and consistent theming across applications.
+
+## Overview
+
+The theme matching system analyzes CSS variables and finds the best matches for any given color based on multiple factors:
+
+- **Perceptual similarity** using HCT color space
+- **Semantic context** from variable naming
+- **Accessibility constraints** for contrast requirements
+- **Confidence scoring** for replacement decisions
+
+## How It Works
+
+### 1. CSS Variable Parsing
+
+The system first extracts and analyzes CSS variables:
+
+```css
+/* Input CSS with theme variables */
+:root {
+  --color-primary-50: #eef2ff;
+  --color-primary-500: #6366f1;
+  --color-primary-900: #312e81;
+  --color-surface: #ffffff;
+  --color-text: #1f2937;
+}
+```
+
+### 2. Semantic Role Detection
+
+Variable names are analyzed to detect semantic roles:
+
+| Pattern | Detected Role | Usage Context |
+|---------|--------------|---------------|
+| `*primary*` | Primary | Main brand color |
+| `*secondary*` | Secondary | Supporting color |
+| `*surface*`, `*background*` | Surface | Backgrounds |
+| `*text*`, `*foreground*` | Text | Typography |
+| `*border*`, `*outline*` | Outline | Borders, dividers |
+| `*error*`, `*danger*` | Error | Error states |
+| `*success*` | Success | Success states |
+| `*warning*` | Warning | Warning states |
+
+### 3. Multi-Factor Scoring
+
+Each potential match is scored based on multiple factors:
+
+#### Perceptual Distance (60% weight)
+Using HCT color space for accurate perception:
+
+```javascript
+function calculatePerceptualDistance(color1, color2) {
+  const hct1 = toHct(color1);
+  const hct2 = toHct(color2);
+
+  // Weighted distance (tone weighted 2x for UI importance)
+  return Math.sqrt(
+    Math.pow(hct1.hue - hct2.hue, 2) +
+    Math.pow(hct1.chroma - hct2.chroma, 2) +
+    Math.pow((hct1.tone - hct2.tone) * 2, 2)
+  );
+}
+```
+
+#### Semantic Context (20% weight)
+Matching semantic roles improves accuracy:
+
+```javascript
+function calculateSemanticScore(colorRole, variableRole, usage) {
+  // Perfect match
+  if (colorRole === variableRole) return 1.0;
+
+  // Compatible roles
+  if (isCompatible(colorRole, variableRole, usage)) return 0.7;
+
+  // Incompatible
+  return 0.3;
+}
+```
+
+#### Accessibility Score (20% weight)
+Ensuring contrast requirements are met:
+
+```javascript
+function calculateAccessibilityScore(color, background, requiredRatio) {
+  const actualRatio = getContrastRatio(color, background);
+
+  if (actualRatio >= requiredRatio) {
+    return 1.0; // Meets requirements
+  }
+
+  // Partial credit based on how close
+  return actualRatio / requiredRatio;
+}
+```
+
+### 4. Confidence Calculation
+
+Final confidence score determines replacement:
+
+```javascript
+confidence = (
+  perceptualScore * 0.6 +
+  semanticScore * 0.2 +
+  accessibilityScore * 0.2
+) * 100;
+```
+
+## Matching Strategies
+
+### Exact Matching
+For colors that exactly match a theme variable:
+- **Confidence**: 100%
+- **Action**: Direct replacement
+- **Example**: `#6366f1` → `var(--color-primary-500)`
+
+### Nearest Neighbor
+For colors close to theme variables:
+- **Confidence**: 70-99%
+- **Action**: Replace with warning
+- **Example**: `#6365f0` → `var(--color-primary-500)` (99% confidence)
+
+### Semantic Matching
+For colors matching expected roles:
+- **Confidence**: 60-90%
+- **Action**: Context-aware replacement
+- **Example**: Border color `#e5e7eb` → `var(--color-border)`
+
+### Fallback Matching
+When no good matches exist:
+- **Confidence**: <60%
+- **Action**: Keep original or create new variable
+- **Example**: `#123456` → `/* No match: #123456 */`
+
+## Usage Examples
+
+### Single Color Matching
+
+```javascript
+// Find best theme variable for a color
+{
+  "name": "match_theme_color",
+  "arguments": {
+    "color": "#6366f1",
+    "themeCSS": ":root { --color-primary: #6366f1; }",
+    "context": "background",
+    "minConfidence": 70
+  }
+}
+
+// Response
+{
+  "match": "--color-primary",
+  "confidence": 100,
+  "originalColor": "#6366f1",
+  "themeColor": "#6366f1",
+  "distance": 0
+}
+```
+
+### CSS Refactoring
+
+```javascript
+// Refactor entire CSS file
+{
+  "name": "refactor_css_with_theme",
+  "arguments": {
+    "css": ".button { background: #6366f1; color: #ffffff; }",
+    "themeCSS": ":root { --primary: #6366f1; --white: #ffffff; }",
+    "minConfidence": 70,
+    "preserveOriginal": true
+  }
+}
+
+// Result
+.button {
+  background: var(--primary); /* was: #6366f1 */
+  color: var(--white); /* was: #ffffff */
+}
+```
+
+### Batch Processing
+
+```javascript
+// Match multiple colors at once
+{
+  "name": "match_theme_colors_batch",
+  "arguments": {
+    "colors": ["#6366f1", "#ec4899", "#10b981"],
+    "themeCSS": "/* theme variables */",
+    "context": "accent"
+  }
+}
+```
+
+## Advanced Features
+
+### Context-Aware Matching
+
+Different contexts have different priorities:
+
+| Context | Priority | Factors |
+|---------|----------|---------|
+| `text` | Contrast > Semantic > Color | Readability first |
+| `background` | Color > Semantic > Contrast | Visual accuracy |
+| `border` | Semantic > Color > Contrast | Structural meaning |
+| `accent` | Color > Contrast > Semantic | Brand consistency |
+| `decorative` | Color > Semantic > Contrast | Visual appeal |
+
+### Threshold Configuration
+
+Fine-tune matching behavior:
+
+```javascript
+{
+  minConfidence: 70,        // Minimum confidence for replacement
+  maxDistance: 10,          // Maximum perceptual distance
+  requireAccessibility: true, // Enforce contrast requirements
+  preserveOriginal: true    // Keep original as comment
+}
+```
+
+### Smart Variable Creation
+
+When no match exists above threshold:
+
+```javascript
+// Input: #123456 with no close match
+// Output:
+:root {
+  --color-custom-1: #123456; /* Auto-generated */
+}
+
+.element {
+  color: var(--color-custom-1);
+}
+```
+
+## Implementation Details
+
+### Parser Architecture
+
+1. **Tokenization**: Break CSS into tokens
+2. **AST Building**: Create abstract syntax tree
+3. **Variable Extraction**: Find all custom properties
+4. **Color Detection**: Identify color values
+5. **Context Analysis**: Determine usage context
+
+### Matching Pipeline
+
+```
+Input Color → HCT Conversion → Distance Calculation
+                                        ↓
+Final Match ← Confidence Score ← Multi-Factor Analysis
+                                        ↑
+                              Semantic & Accessibility
+```
+
+### Performance Optimization
+
+- **Caching**: Theme variables cached after first parse
+- **Indexing**: Pre-computed HCT values for all theme colors
+- **Batching**: Process multiple colors in single pass
+- **Early Exit**: Skip processing if exact match found
+
+## Best Practices
+
+### Theme Variable Naming
+
+Use semantic, hierarchical naming:
+
+```css
+/* Good - Clear hierarchy and purpose */
+--color-primary-50
+--color-primary-500
+--color-primary-900
+--color-text-primary
+--color-text-secondary
+
+/* Avoid - Ambiguous or color-specific */
+--blue
+--light-blue
+--text-color
+--col1
+```
+
+### Confidence Thresholds
+
+Recommended thresholds by use case:
+
+| Use Case | Min Confidence | Rationale |
+|----------|---------------|-----------|
+| Production refactor | 85% | High accuracy needed |
+| Development assist | 70% | Balance speed/accuracy |
+| Exploration | 50% | See all possibilities |
+| Exact only | 100% | No false positives |
+
+### Handling Edge Cases
+
+#### Very Similar Colors
+```css
+/* Original */
+.element1 { color: #6366f1; }
+.element2 { color: #6366f0; }
+
+/* After matching - both map to same variable */
+.element1 { color: var(--color-primary); }
+.element2 { color: var(--color-primary); }
+```
+
+#### No Good Matches
+```css
+/* Original */
+.special { background: #742a2a; }
+
+/* After - preserved with comment */
+.special {
+  background: #742a2a; /* No theme match (confidence: 45%) */
+}
+```
+
+## Integration Patterns
+
+### Build Tools
+
+```javascript
+// Webpack plugin example
+module.exports = {
+  plugins: [
+    new ThemeMatcherPlugin({
+      themeFile: './theme.css',
+      minConfidence: 80,
+      generateReport: true
+    })
+  ]
+};
+```
+
+### CI/CD Pipeline
+
+```yaml
+# GitHub Actions example
+- name: Refactor CSS with Theme
+  run: |
+    coolors-mcp refactor \
+      --input src/styles \
+      --theme src/theme.css \
+      --confidence 85 \
+      --report
+```
+
+### IDE Extensions
+
+```javascript
+// VS Code extension config
+"coolors.themeMatching": {
+  "enabled": true,
+  "themeFile": "${workspaceFolder}/theme.css",
+  "minConfidence": 75,
+  "showInlineHints": true
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Low Confidence Scores
+- **Cause**: Colors too different from theme
+- **Solution**: Lower threshold or add more theme variables
+
+#### Wrong Semantic Matches
+- **Cause**: Ambiguous variable names
+- **Solution**: Use clearer naming conventions
+
+#### Accessibility Failures
+- **Cause**: Insufficient contrast with background
+- **Solution**: Adjust theme colors or use different variables
+
+### Debugging
+
+Enable detailed logging:
+
+```javascript
+{
+  "generateReport": true,
+  "verboseLogging": true,
+  "showDistanceMatrix": true
+}
+```
+
+## See Also
+
+- [Color Spaces](./color-spaces.md) - Understanding color models
+- [HCT System](./hct.md) - Perceptual color space
+- [Accessibility](./accessibility.md) - Contrast requirements
+- [Material Design](./material-design.md) - Theme generation