{"id":28572327,"url":"https://github.com/a-ng-d/utils-ui-color-palette","last_synced_at":"2026-04-19T16:01:11.790Z","repository":{"id":295151244,"uuid":"989328085","full_name":"a-ng-d/utils-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-04-02T16:43:35.000Z","size":468,"stargazers_count":1,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T04:46:40.735Z","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-04-02T16:43:37.000Z","dependencies_parsed_at":"2026-01-07T23:07:38.405Z","dependency_job_id":null,"html_url":"https://github.com/a-ng-d/utils-ui-color-palette","commit_stats":null,"previous_names":["a-ng-d/utils-ui-color-palette"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/a-ng-d/utils-ui-color-palette","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-ng-d%2Futils-ui-color-palette","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-ng-d%2Futils-ui-color-palette/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-ng-d%2Futils-ui-color-palette/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-ng-d%2Futils-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/utils-ui-color-palette/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-ng-d%2Futils-ui-color-palette/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32012787,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"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":"2025-06-10T20:14:40.008Z","updated_at":"2026-04-19T16:01:11.778Z","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/utils-ui-color-palette?color=informational) ![GitHub last commit](https://img.shields.io/github/last-commit/a-ng-d/utils-ui-color-palette?color=informational) ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/a-ng-d/utils-ui-color-palette/npm.yml?label=npm)\n![GitHub](https://img.shields.io/github/license/a-ng-d/utils-ui-color-palette?color=informational)\n\n# UI Color Palette Utils\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- **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 @a_ng_d/utils-ui-color-palette\n# or\nyarn add @a_ng_d/utils-ui-color-palette\n```\n\n## Usage\n\n```typescript\nimport {\n  Color,\n  Contrast,\n  Data,\n  DominantColors,\n  ColorHarmony,\n} from '@a_ng_d/utils-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 '@a_ng_d/utils-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 '@a_ng_d/utils-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 '@a_ng_d/utils-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 '@a_ng_d/utils-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    \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 '@a_ng_d/utils-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 '@a_ng_d/utils-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## 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**     | **91.61** | **87.27** | **91.59** | **91.61** |\n| code              | 100     | 100      | 100     | 100     |\n| color             | 93.54   | 77.51    | 83.33   | 93.54   |\n| color-harmony     | 100     | 96.66    | 100     | 100     |\n| contrast          | 89      | 93.33    | 100     | 89      |\n| data              | 93.48   | 89.74    | 100     | 93.48   |\n| dominant-colors   | 77.58   | 89.06    | 90.47   | 77.58   |\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%2Futils-ui-color-palette","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fa-ng-d%2Futils-ui-color-palette","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa-ng-d%2Futils-ui-color-palette/lists"}