eva-colors 1.0.0

package/README.md

@@ -0,0 +1,219 @@
+# @eva/colors
+
+> OKLCH color utilities for EVA CSS framework
+
+Powerful color conversion and manipulation tools focused on the perceptually uniform OKLCH color space.
+
+## 🎯 Features
+
+- **Hex ↔ OKLCH Conversion**: Seamless conversion between color formats
+- **Palette Generation**: Create harmonious color palettes from a base color
+- **Theme Generator**: Generate EVA CSS themes from color configs
+- **Accessibility Checks**: WCAG contrast validation
+- **CLI & Programmatic API**: Use via command line or in your code
+
+## 📦 Installation
+
+```bash
+npm install @eva/colors
+# or
+pnpm add @eva/colors
+# or
+yarn add @eva/colors
+```
+
+## 🚀 Usage
+
+### CLI Usage
+
+```bash
+# Convert hex to OKLCH
+eva-color convert #ff0000
+
+# Convert OKLCH to hex
+eva-color to-hex 62.8 0.258 29.23
+
+# Generate a 7-step palette
+eva-color palette #ff0000 7
+
+# Generate theme CSS
+eva-color theme my-theme.json
+
+# Check color contrast
+eva-color contrast #ffffff #000000
+```
+
+### Programmatic Usage
+
+```javascript
+import {
+  hexToOklch,
+  oklchToHex,
+  generatePalette,
+  generateTheme,
+  checkAccessibility
+} from '@eva/colors';
+
+// Convert hex to OKLCH
+const oklch = hexToOklch('#ff0000');
+console.log(oklch);
+// {
+//   l: 62.8,
+//   c: 0.258,
+//   h: 29.23,
+//   css: 'oklch(62.8% 0.258 29.23)',
+//   scss: {
+//     lightness: '62.8%',
+//     chroma: '0.258',
+//     hue: '29.23'
+//   }
+// }
+
+// Convert OKLCH to hex
+const hex = oklchToHex({ l: 62.8, c: 0.258, h: 29.23 });
+console.log(hex); // '#ff0000'
+
+// Generate palette
+const palette = generatePalette('#ff0000', 5);
+console.log(palette);
+// [
+//   { hex: '#...', oklch: {...}, name: 'step-1' },
+//   { hex: '#...', oklch: {...}, name: 'step-2' },
+//   ...
+// ]
+
+// Generate theme
+const theme = generateTheme({
+  name: 'my-theme',
+  brand: '#ff0000',
+  accent: '#7300ff',
+  extra: '#ffe500',
+  light: '#f3f3f3',
+  dark: '#252525'
+});
+console.log(theme);
+// .theme-my-theme {
+//   --brand-lightness: 62.8%;
+//   --brand-chroma: 0.258;
+//   --brand-hue: 29.23;
+//   ...
+// }
+
+// Check accessibility
+const result = checkAccessibility('#ffffff', '#000000', 'AA');
+console.log(result);
+// {
+//   pass: true,
+//   contrast: '0.821',
+//   level: 'AA'
+// }
+```
+
+## 📚 API Reference
+
+### `hexToOklch(hex)`
+
+Convert hex color to OKLCH format.
+
+**Parameters:**
+- `hex` (string): Hex color code (e.g., "#ff0000")
+
+**Returns:** Object with OKLCH values and CSS/SCSS formats, or `null` if invalid
+
+### `oklchToHex({ l, c, h })`
+
+Convert OKLCH color to hex format.
+
+**Parameters:**
+- `l` (number): Lightness (0-100)
+- `c` (number): Chroma (0-0.4)
+- `h` (number): Hue (0-360)
+
+**Returns:** Hex color string, or `null` if invalid
+
+### `generatePalette(baseColor, steps = 5)`
+
+Generate a color palette from a base color.
+
+**Parameters:**
+- `baseColor` (string): Base hex color
+- `steps` (number): Number of palette steps (default: 5)
+
+**Returns:** Array of color objects
+
+### `generateTheme(config)`
+
+Generate EVA CSS theme variables from config.
+
+**Parameters:**
+- `config` (object): Theme configuration
+  - `name` (string): Theme name
+  - `brand` (string): Brand color hex
+  - `accent` (string): Accent color hex
+  - `extra` (string): Extra color hex
+  - `light` (string): Light color hex
+  - `dark` (string): Dark color hex
+
+**Returns:** CSS string with theme variables
+
+### `checkAccessibility(foreground, background, level = 'AA')`
+
+Check WCAG contrast requirements.
+
+**Parameters:**
+- `foreground` (string): Foreground hex color
+- `background` (string): Background hex color
+- `level` (string): 'AA' or 'AAA' (default: 'AA')
+
+**Returns:** Object with pass/fail result and contrast value
+
+## 🎨 Example: Figma to EVA Workflow
+
+```bash
+# 1. Extract colors from Figma
+# (via Figma MCP or manually)
+
+# 2. Convert to OKLCH
+eva-color convert #ff5733
+
+# 3. Create theme config (theme.json)
+{
+  "name": "my-project",
+  "brand": "#ff5733",
+  "accent": "#33ff57",
+  "extra": "#3357ff",
+  "light": "#f5f5f5",
+  "dark": "#1a1a1a"
+}
+
+# 4. Generate theme CSS
+eva-color theme theme.json > my-theme.scss
+
+# 5. Use in your EVA CSS project
+```
+
+## 🌈 Why OKLCH?
+
+OKLCH is a perceptually uniform color space that provides:
+
+- **Better color interpolation**: Smooth gradients without muddy midtones
+- **Predictable lightness**: L values directly correlate to perceived brightness
+- **Wide gamut support**: Access to vibrant colors beyond sRGB
+- **Consistent chroma**: Colors with same C value have similar saturation
+
+## 📄 License
+
+MIT © [Michaël Tati](https://ulysse-2029.com/)
+
+## 👨‍💻 Author
+
+**Michaël Tati**
+- Portfolio: [ulysse-2029.com](https://ulysse-2029.com/)
+- LinkedIn: [linkedin.com/in/mtati](https://www.linkedin.com/in/mtati/)
+- Website: [eva-css.xyz](https://eva-css.xyz/)
+
+## 🔗 Related Packages
+
+- [@eva/css](https://www.npmjs.com/package/@eva/css) - Fluid design framework
+- [@eva/purge](https://www.npmjs.com/package/@eva/purge) - CSS optimization tool
+- [@eva/mcp-server](https://www.npmjs.com/package/@eva/mcp-server) - Figma to HTML MCP server

package/cli.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+// ===========================================
+// EVA Colors CLI
+// ===========================================
+
+import { hexToOklch, oklchToHex, generatePalette, generateTheme, checkAccessibility } from './src/index.js';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function printHelp() {
+  console.log(`
+EVA Colors CLI - OKLCH Color Utilities
+
+Usage:
+  eva-color <command> [options]
+
+Commands:
+  convert <hex>              Convert hex to OKLCH
+  to-hex <l> <c> <h>        Convert OKLCH to hex
+  palette <hex> [steps]      Generate color palette (default 5 steps)
+  theme <config.json>        Generate theme from JSON config
+  contrast <hex1> <hex2>     Check color contrast
+  help                       Show this help message
+
+Examples:
+  eva-color convert #ff0000
+  eva-color to-hex 62.8 0.258 29.23
+  eva-color palette #ff0000 7
+  eva-color contrast #ffffff #000000
+
+Theme config example (theme.json):
+{
+  "name": "my-theme",
+  "brand": "#ff0000",
+  "accent": "#7300ff",
+  "extra": "#ffe500",
+  "light": "#f3f3f3",
+  "dark": "#252525"
+}
+  `);
+}
+
+// Command handlers
+switch (command) {
+  case 'convert': {
+    const hex = args[1];
+    if (!hex) {
+      console.error('❌ Error: Hex color required');
+      console.log('Usage: eva-color convert #ff0000');
+      process.exit(1);
+    }
+
+    const result = hexToOklch(hex);
+    if (!result) {
+      console.error(`❌ Error: Invalid hex color "${hex}"`);
+      process.exit(1);
+    }
+
+    console.log(`\n🎨 Conversion: ${hex} → OKLCH\n`);
+    console.log(`CSS:  ${result.css}`);
+    console.log(`\nSCSS Variables:`);
+    console.log(`  --lightness: ${result.scss.lightness};`);
+    console.log(`  --chroma: ${result.scss.chroma};`);
+    console.log(`  --hue: ${result.scss.hue};`);
+    console.log();
+    break;
+  }
+
+  case 'to-hex': {
+    const l = parseFloat(args[1]);
+    const c = parseFloat(args[2]);
+    const h = parseFloat(args[3]);
+
+    if (isNaN(l) || isNaN(c) || isNaN(h)) {
+      console.error('❌ Error: Invalid OKLCH values');
+      console.log('Usage: eva-color to-hex 62.8 0.258 29.23');
+      process.exit(1);
+    }
+
+    const hex = oklchToHex({ l, c, h });
+    if (!hex) {
+      console.error('❌ Error: Conversion failed');
+      process.exit(1);
+    }
+
+    console.log(`\n🎨 Conversion: OKLCH → ${hex}\n`);
+    break;
+  }
+
+  case 'palette': {
+    const hex = args[1];
+    const steps = parseInt(args[2]) || 5;
+
+    if (!hex) {
+      console.error('❌ Error: Base hex color required');
+      console.log('Usage: eva-color palette #ff0000 [steps]');
+      process.exit(1);
+    }
+
+    const palette = generatePalette(hex, steps);
+    if (palette.length === 0) {
+      console.error(`❌ Error: Invalid hex color "${hex}"`);
+      process.exit(1);
+    }
+
+    console.log(`\n🎨 Generated ${steps}-step palette from ${hex}\n`);
+    palette.forEach((color, i) => {
+      console.log(`${i + 1}. ${color.hex} → ${color.oklch.css}`);
+    });
+    console.log();
+    break;
+  }
+
+  case 'theme': {
+    const configPath = args[1];
+    if (!configPath) {
+      console.error('❌ Error: Config file required');
+      console.log('Usage: eva-color theme config.json');
+      process.exit(1);
+    }
+
+    try {
+      const fs = await import('fs');
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+      const css = generateTheme(config);
+
+      console.log(`\n🎨 Generated theme: ${config.name}\n`);
+      console.log(css);
+      console.log();
+    } catch (error) {
+      console.error(`❌ Error: ${error.message}`);
+      process.exit(1);
+    }
+    break;
+  }
+
+  case 'contrast': {
+    const hex1 = args[1];
+    const hex2 = args[2];
+
+    if (!hex1 || !hex2) {
+      console.error('❌ Error: Two hex colors required');
+      console.log('Usage: eva-color contrast #ffffff #000000');
+      process.exit(1);
+    }
+
+    const resultAA = checkAccessibility(hex1, hex2, 'AA');
+    const resultAAA = checkAccessibility(hex1, hex2, 'AAA');
+
+    console.log(`\n🎨 Contrast Check: ${hex1} vs ${hex2}\n`);
+    console.log(`Contrast Value: ${resultAA.contrast}`);
+    console.log(`WCAG AA:  ${resultAA.pass ? '✅ Pass' : '❌ Fail'}`);
+    console.log(`WCAG AAA: ${resultAAA.pass ? '✅ Pass' : '❌ Fail'}`);
+    console.log();
+    break;
+  }
+
+  case 'help':
+  case undefined:
+    printHelp();
+    break;
+
+  default:
+    console.error(`❌ Error: Unknown command "${command}"`);
+    printHelp();
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "eva-colors",
+  "version": "1.0.0",
+  "description": "OKLCH color utilities for EVA CSS framework",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "eva-color": "./cli.js"
+  },
+  "files": [
+    "src/",
+    "cli.js",
+    "README.md"
+  ],
+  "keywords": [
+    "color",
+    "oklch",
+    "css",
+    "eva",
+    "color-conversion",
+    "hex-to-oklch",
+    "palette-generator"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "dev": "node --watch cli.js"
+  },
+  "dependencies": {
+    "culori": "^4.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nkdeus/eva.git",
+    "directory": "packages/eva-colors"
+  },
+  "author": {
+    "name": "Michaël Tati",
+    "url": "https://ulysse-2029.com/"
+  },
+  "homepage": "https://eva-css.xyz/",
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,149 @@
+// ===========================================
+// EVA Colors - OKLCH Color Utilities
+// ===========================================
+
+import { parse, oklch, formatHex, differenceEuclidean } from 'culori';
+
+/**
+ * Convert hex color to OKLCH format
+ * @param {string} hex - Hex color code (e.g., "#ff0000")
+ * @returns {Object|null} OKLCH color object with CSS string
+ */
+export function hexToOklch(hex) {
+  const color = parse(hex);
+  if (!color) return null;
+
+  const oklchColor = oklch(color);
+  if (!oklchColor) return null;
+
+  const { l, c, h } = oklchColor;
+
+  return {
+    l: Math.round(l * 1000) / 10, // Percentage with 1 decimal
+    c: Math.round(c * 1000) / 1000, // 3 decimals
+    h: h !== undefined ? Math.round(h * 100) / 100 : 0, // 2 decimals
+    css: `oklch(${(l * 100).toFixed(1)}% ${c.toFixed(3)} ${h !== undefined ? h.toFixed(2) : '0'})`,
+    scss: {
+      lightness: `${(l * 100).toFixed(1)}%`,
+      chroma: c.toFixed(3),
+      hue: (h !== undefined ? h.toFixed(2) : '0')
+    }
+  };
+}
+
+/**
+ * Convert OKLCH to hex color
+ * @param {Object} oklchColor - {l: 0-100, c: 0-0.4, h: 0-360}
+ * @returns {string|null} Hex color code
+ */
+export function oklchToHex({ l, c, h }) {
+  try {
+    return formatHex({ mode: 'oklch', l: l / 100, c, h });
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Generate a palette of colors based on a base color
+ * @param {string} baseColor - Base hex color
+ * @param {number} steps - Number of palette steps (default: 5)
+ * @returns {Array} Array of color objects
+ */
+export function generatePalette(baseColor, steps = 5) {
+  const base = hexToOklch(baseColor);
+  if (!base) return [];
+
+  const palette = [];
+  const lightnessRange = 90 - 10; // From 10% to 90%
+  const stepSize = lightnessRange / (steps - 1);
+
+  for (let i = 0; i < steps; i++) {
+    const lightness = 10 + (i * stepSize);
+    const color = oklchToHex({
+      l: lightness,
+      c: base.c * (lightness / base.l), // Adjust chroma based on lightness
+      h: base.h
+    });
+
+    palette.push({
+      hex: color,
+      oklch: hexToOklch(color),
+      name: `step-${i + 1}`
+    });
+  }
+
+  return palette;
+}
+
+/**
+ * Generate theme CSS variables from config
+ * @param {Object} config - Theme configuration
+ * @returns {string} CSS variables
+ */
+export function generateTheme(config) {
+  const {
+    name = 'custom',
+    brand,
+    accent,
+    extra,
+    light,
+    dark
+  } = config;
+
+  const colors = { brand, accent, extra, light, dark };
+  let css = `.theme-${name} {\n`;
+
+  for (const [colorName, hexColor] of Object.entries(colors)) {
+    if (!hexColor) continue;
+
+    const oklchColor = hexToOklch(hexColor);
+    if (!oklchColor) continue;
+
+    css += `  --${colorName}-lightness: ${oklchColor.scss.lightness};\n`;
+    css += `  --${colorName}-chroma: ${oklchColor.scss.chroma};\n`;
+    css += `  --${colorName}-hue: ${oklchColor.scss.hue};\n`;
+    css += `\n`;
+  }
+
+  css += `}`;
+  return css;
+}
+
+/**
+ * Calculate color contrast ratio
+ * @param {string} hex1 - First hex color
+ * @param {string} hex2 - Second hex color
+ * @returns {number|null} Contrast ratio
+ */
+export function getContrast(hex1, hex2) {
+  const color1 = parse(hex1);
+  const color2 = parse(hex2);
+
+  if (!color1 || !color2) return null;
+
+  // Use Euclidean distance in OKLCH space as a simple contrast metric
+  return differenceEuclidean()(oklch(color1), oklch(color2));
+}
+
+/**
+ * Check if color meets WCAG contrast requirements
+ * @param {string} foreground - Foreground hex color
+ * @param {string} background - Background hex color
+ * @param {string} level - 'AA' or 'AAA' (default: 'AA')
+ * @returns {Object} Accessibility check result
+ */
+export function checkAccessibility(foreground, background, level = 'AA') {
+  const contrast = getContrast(foreground, background);
+  if (contrast === null) return { pass: false, contrast: null };
+
+  // Simplified check using Euclidean distance
+  // Threshold values are approximations
+  const threshold = level === 'AAA' ? 0.15 : 0.10;
+
+  return {
+    pass: contrast >= threshold,
+    contrast: contrast.toFixed(3),
+    level
+  };
+}