{"id":51842101,"url":"https://github.com/a-ng-d/engine-ui-color-palette","last_synced_at":"2026-07-23T07:01:07.457Z","repository":{"id":295151244,"uuid":"989328085","full_name":"a-ng-d/engine-ui-color-palette","owner":"a-ng-d","description":"Core utilities library for UI Color Palette - a color management plugin for design tools. This library provides the foundational color manipulation, contrast calculation, and palette generation features used in the plugin.","archived":false,"fork":false,"pushed_at":"2026-07-16T16:40:31.000Z","size":951,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-16T17:21:59.175Z","etag":null,"topics":["apca","color","contrast","wcag2","wcag3"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/a-ng-d.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-23T22:11:59.000Z","updated_at":"2026-07-16T16:40:46.000Z","dependencies_parsed_at":"2026-01-07T23:07:38.405Z","dependency_job_id":"202f192d-82ff-4549-b8c7-8402da826868","html_url":"https://github.com/a-ng-d/engine-ui-color-palette","commit_stats":null,"previous_names":["a-ng-d/utils-ui-color-palette","a-ng-d/engine-ui-color-palette"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/a-ng-d/engine-ui-color-palette","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-ng-d%2Fengine-ui-color-palette","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-ng-d%2Fengine-ui-color-palette/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-ng-d%2Fengine-ui-color-palette/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-ng-d%2Fengine-ui-color-palette/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/a-ng-d","download_url":"https://codeload.github.com/a-ng-d/engine-ui-color-palette/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-ng-d%2Fengine-ui-color-palette/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35793062,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apca","color","contrast","wcag2","wcag3"],"created_at":"2026-07-23T07:01:06.690Z","updated_at":"2026-07-23T07:01:07.450Z","avatar_url":"https://github.com/a-ng-d.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"![GitHub package.json version](https://img.shields.io/github/package-json/v/a-ng-d/engine-ui-color-palette?color=informational) ![GitHub last commit](https://img.shields.io/github/last-commit/a-ng-d/engine-ui-color-palette?color=informational) ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/a-ng-d/engine-ui-color-palette/npm.yml?label=npm)\n![GitHub](https://img.shields.io/github/license/a-ng-d/engine-ui-color-palette?color=informational)\n\n# UI Color Palette Engine\n\nCore utilities library for UI Color Palette - a color management plugin for design tools. This library provides the foundational color manipulation, contrast calculation, and palette generation features used in the plugin.\n\n## Design Tools Compatibility\n\nUI Color Palette is available for:\n\n- Figma - Create and manage color primitives directly in your Figma designs\n- FigJam - Collaborate on color decisions with your team\n- Penpot - Open-source design tool alternative with full color management support\n\n## Features\n\n- **Color Contrast Tools**:\n\n  - APCA contrast calculations\n  - WCAG 2.1 compliance checking\n  - Contrast ratio calculations between colors\n  - Pre-computed text contrast scores (light/dark) per shade\n\n- **Color Manipulation**:\n\n  - Color space conversions (RGB, HSL, HSLuv, LAB)\n  - Color mixing and blending\n  - Brightness and saturation adjustments\n\n- **Dominant Colors Extraction**:\n\n  - Extract dominant colors from images using K-means clustering\n  - Configurable number of colors to extract\n  - Automatic color frequency calculation\n  - Support for transparent pixel filtering\n\n- **Color Harmony Generation**:\n\n  - Generate analogous, complementary, triadic, tetradic, square, and compound color harmonies\n  - Configurable analogous spread angle\n  - Automatic color relationship calculations\n  - Support for all major color harmony types\n\n- **Color System \u0026 Semantic Tokens**:\n\n  - Build a semantic color system from a taxonomy schema and palette data\n  - Bind semantic tokens to primitive shades with optional per-theme overrides\n  - Exclude specific tokens from code generation via the `isExcluded` flag\n  - Generate semantic token files for CSS, SCSS, LESS, DTCG, Tailwind v3/v4, SwiftUI, UIKit, Compose, Native, Universal, CSV, Android Resources, and Style Dictionary v3\n\n- **Palette Generation**:\n  - Create harmonious color schemes\n  - Generate accessible color combinations\n  - Scale generation for design systems\n\n## Installation\n\n```bash\nnpm install @yelbolt/engine-ui-color-palette\n# or\nyarn add @yelbolt/engine-ui-color-palette\n```\n\n## Usage\n\n```typescript\nimport {\n  Color,\n  Contrast,\n  Data,\n  DominantColors,\n  ColorHarmony,\n} from '@yelbolt/engine-ui-color-palette'\n\n// Use Color class for color manipulation\nconst color = new Color({\n  sourceColor: [255, 0, 0], // RGB values\n  lightness: 50,\n  hueShifting: 0,\n  chromaShifting: 100,\n})\n\n// Use Contrast class for accessibility checks\nconst contrast = new Contrast({\n  backgroundColor: [255, 255, 255],\n  textColor: '#000000',\n})\n\n// Use Data class for palette generation\nconst data = new Data({\n  base: baseConfig,\n  themes: themesConfig,\n  meta: metaConfig,\n})\n```\n\n## Examples\n\n### Color Manipulation\n\n```typescript\nimport { Color } from '@yelbolt/engine-ui-color-palette'\n\n// Create a color instance\nconst color = new Color({\n  sourceColor: [255, 0, 0], // Red in RGB\n  lightness: 50,\n  chromaShifting: 100,\n})\n\n// Convert to different color spaces\nconst lchColor = color.lch() // Returns LCH color\nconst oklchColor = color.oklch() // Returns OKLCH color\nconst hslColor = color.hsl() // Returns HSL color\nconst labColor = color.lab() // Returns LAB color\n\n// Mix colors\nconst mixedRgb = color.mixColorsRgb(\n  [255, 0, 0, 0.5], // Semi-transparent red\n  [0, 0, 255, 1] // Solid blue\n)\n\nconst mixedHex = color.mixColorsHex('#FF0000', '#0000FF')\n```\n\n### Contrast Calculations\n\n```typescript\nimport { Contrast } from '@yelbolt/engine-ui-color-palette'\n\n// Create a contrast checker instance\nconst contrast = new Contrast({\n  backgroundColor: [255, 255, 255], // White background\n  textColor: '#000000', // Black text\n})\n\n// Get contrast values\nconst wcagContrast = contrast.getWCAGContrast() // WCAG 2.1 contrast ratio\nconst apcaContrast = contrast.getAPCAContrast() // APCA contrast value\nconst wcagScore = contrast.getWCAGScore() // Returns: 'AAA', 'AA', or 'A'\n\n// Get accessibility recommendations\nconst usage = contrast.getRecommendedUsage() // Returns usage recommendation\nconst minSizes = contrast.getMinFontSizes() // Returns minimum font sizes\n\n// Find specific contrast values\nconst lightness = contrast.getLightnessForContrastRatio(4.5) // For WCAG AA\n```\n\n### Dominant Colors Extraction\n\n```typescript\nimport { DominantColors } from '@yelbolt/engine-ui-color-palette'\n\n// Prepare your image data (from canvas, file, etc.)\nconst canvas = document.createElement('canvas')\nconst ctx = canvas.getContext('2d')\n// ... load your image into the canvas\nconst imageData = ctx.getImageData(0, 0, canvas.width, canvas.height)\n\n// Create a dominant colors extractor\nconst dominantColors = new DominantColors({\n  imageData: imageData,\n  colorCount: 5, // Extract top 5 colors\n  maxIterations: 50, // K-means algorithm iterations\n  tolerance: 0.01, // Convergence tolerance\n  skipTransparent: true, // Skip transparent pixels\n})\n\n// Extract the dominant colors\nconst colors = dominantColors.extractDominantColors()\n\n// Results array contains:\ncolors.forEach((result) =\u003e {\n  console.log({\n    color: result.color, // RGB array: [r, g, b]\n    hex: result.hex, // Hex string: \"#ff0000\"\n    percentage: result.percentage, // Percentage of image: 25.5\n    count: result.count, // Number of pixels: 1000\n  })\n})\n\n// Update settings dynamically\ndominantColors.setColorCount(8) // Change to 8 colors\ndominantColors.updateOptions({\n  maxIterations: 100,\n  tolerance: 0.005,\n})\n\n// Get current configuration\nconst options = dominantColors.getOptions()\n```\n\n#### Working with File Uploads (ArrayBuffer)\n\nFor modern web applications that need to extract colors from uploaded image files:\n\n```typescript\nimport { DominantColors } from '@yelbolt/engine-ui-color-palette'\n\n// Handle file upload from user input\nconst handleImageUpload = async (event: Event) =\u003e {\n  const file = (event.target as HTMLInputElement).files?.[0]\n  if (!file) return\n\n  // Convert file to ArrayBuffer\n  const arrayBuffer = await file.arrayBuffer()\n\n  try {\n    // Simple usage: extract 5 dominant colors\n    const colors = await DominantColors.extract(arrayBuffer, 5)\n\n    console.log('Extracted colors:', colors)\n    // Each color object contains: { color, hex, percentage, count }\n  } catch (error) {\n    console.error('Error extracting colors:', error)\n  }\n}\n\n// Advanced usage with custom options\nconst extractColorsAdvanced = async (arrayBuffer: ArrayBuffer) =\u003e {\n  const colors = await DominantColors.fromArrayBuffer(arrayBuffer, {\n    colorCount: 8,\n    maxIterations: 100,\n    tolerance: 0.005,\n    skipTransparent: true,\n    maxImageSize: 300, // Resize large images for faster processing\n  })\n\n  return colors\n}\n\n// HTML file input example\n// \u003cinput type=\"file\" accept=\"image/*\" onChange={handleImageUpload} /\u003e\n```\n\n**Note**: ArrayBuffer extraction requires a browser environment with Canvas API support.\n\n### Color Harmony Generation\n\n```typescript\nimport { ColorHarmony } from '@yelbolt/engine-ui-color-palette'\n\n// Create a color harmony generator\nconst colorHarmony = new ColorHarmony({\n  baseColor: [255, 0, 0], // Red base color\n  analogousSpread: 30, // 30 degrees for analogous colors\n})\n\n// Generate specific harmony types\nconst analogous = colorHarmony.generateAnalogous()\nconst complementary = colorHarmony.generateComplementary()\nconst triadic = colorHarmony.generateTriadic()\nconst tetradic = colorHarmony.generateTetradic()\nconst square = colorHarmony.generateSquare()\nconst compound = colorHarmony.generateCompound()\n\n// Generate harmony by type\nconst harmony = colorHarmony.generateHarmony('TRIADIC')\n\n// Generate all harmonies at once (now includes 6 harmonies)\nconst allHarmonies = colorHarmony.getAllHarmonies()\n\n// Results contain both RGB and hex values\nconsole.log(triadic.colors) // [[255, 0, 0], [0, 255, 0], [0, 0, 255]]\nconsole.log(triadic.hexColors) // ['#ff0000', '#00ff00', '#0000ff']\n\n// Update settings\ncolorHarmony.setBaseColor([0, 128, 255])\ncolorHarmony.setAnalogousSpread(45)\ncolorHarmony.updateOptions({\n  analogousSpread: 60,\n  returnFormat: 'hex',\n})\n```\n\n### Palette Generation\n\n```typescript\nimport { Data } from '@yelbolt/engine-ui-color-palette'\n\n// Configure your palette\nconst config = {\n  base: {\n    name: 'My Palette',\n    colors: [\n      /* your colors */\n    ],\n    colorSpace: 'LAB',\n    algorithmVersion: 'v3',\n  },\n  themes: [\n    {\n      id: 'light',\n      name: 'Light Theme',\n      scale: {\n        /* lightness values */\n      },\n      visionSimulationMode: 'NONE',\n    },\n  ],\n  meta: {\n    /* metadata */\n  },\n}\n\n// Create a data instance\nconst data = new Data(config)\n\n// Generate palette data\nconst paletteData = data.makePaletteData()\nconst fullData = data.makePaletteFullData()\n\n// Access pre-computed text contrast scores\npaletteData.themes[0].colors[0].shades.forEach((shade) =\u003e {\n  if (shade.textContrast) {\n    // WCAG scores for light/dark text on this shade\n    console.log(shade.textContrast.wcag.light) // { ratio: 4.5, score: 'AA' }\n    console.log(shade.textContrast.wcag.dark) // { ratio: 12.6, score: 'AAA' }\n\n    // APCA scores for light/dark text on this shade\n    console.log(shade.textContrast.apca.light) // { lc: -60.2, recommendedUsage: 'BODY_TEXT' }\n    console.log(shade.textContrast.apca.dark) // { lc: 85.1, recommendedUsage: 'FLUENT_TEXT' }\n  }\n})\n```\n\n### Color System \u0026 Semantic Tokens\n\n```typescript\nimport { System, Code } from '@yelbolt/engine-ui-color-palette'\n\n// Define a taxonomy schema (groups of semantic dimensions)\nconst system = new System({\n  paletteData,\n  system: {\n    schema: {\n      groups: [\n        {\n          id: 'role',\n          name: 'Role',\n          members: [\n            { id: 'brand', name: 'Brand' },\n            { id: 'neutral', name: 'Neutral' },\n          ],\n        },\n        {\n          id: 'prominence',\n          name: 'Prominence',\n          members: [\n            { id: 'default', name: 'Default' },\n            { id: 'subtle', name: 'Subtle' },\n          ],\n        },\n      ],\n    },\n    bindings: [\n      {\n        path: ['brand', 'default'],\n        description: 'Primary brand color',\n        ref: 'blue:500',\n        overrides: { dark: 'blue:400' }, // per-theme override\n      },\n      {\n        path: ['neutral', 'subtle'],\n        ref: 'gray:200',\n        isExcluded: true, // skip this token in code generation\n      },\n    ],\n  },\n})\n\n// Resolve the system data (tokens + refs)\nconst systemData = system.makeSystemData()\n\n// Generate semantic token files alongside primitives\nconst code = new Code({ paletteData, systemData })\nconst files = code.makeCssFiles()\n// files[0].content includes both --color-blue-500 primitives\n// and --brand-default / --neutral-default semantic custom properties\n```\n\n## Testing\n\n```bash\nnpm test\n# or\nyarn test\n```\n\n## Code Coverage\n\nCurrent test coverage results:\n\n| File               | % Stmts   | % Branch  | % Funcs   | % Lines   |\n| ------------------ | --------- | --------- | --------- | --------- |\n| **All files**      | **92.66** | **88.34** | **92.18** | **92.66** |\n| code.ts            | 100       | 100       | 100       | 100       |\n| color.ts           | 93.4      | 77.51     | 83.33     | 93.4      |\n| color-harmony.ts   | 100       | 96.66     | 100       | 100       |\n| contrast.ts        | 89        | 93.33     | 100       | 89        |\n| data.ts            | 93.69     | 89.8      | 100       | 93.69     |\n| dominant-colors.ts | 77.58     | 89.06     | 90.47     | 77.58     |\n| system.ts          | 100       | 91.3      | 100       | 100       |\n\nTo run coverage tests:\n\n```bash\nnpm run test:coverage\n```\n\n## Credits\n\nThis project relies on several excellent open source packages:\n\n### Color Processing\n\n- [chroma.js](https://gka.github.io/chroma.js/) - A powerful library for color manipulations and conversions\n  - Author: Gregor Aisch\n  - License: BSD-3-Clause\n\n### Contrast Calculation\n\n- [APCA-W3](https://github.com/Myndex/SAPC-APCA) - Advanced Perceptual Contrast Algorithm\n  - Author: Andrew Somers\n  - License: W3C Software and Document Notice and License\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa-ng-d%2Fengine-ui-color-palette","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fa-ng-d%2Fengine-ui-color-palette","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa-ng-d%2Fengine-ui-color-palette/lists"}