PaletteLab

Extract • Analyze • Generate Professional Color Systems

A highly polished, client-side web application that intelligently extracts perceptually accurate color systems from images and generates production-ready assets for designers and developers.

---

📖 Table of Contents

• About the Project
• Key Features
• How It Works (Under the Hood)
• Tech Stack & Architecture
• Export Formats
• Local Development

---

⚡ About the Project

PaletteLab bridges the gap between raw inspiration and engineering implementation. Designed with a premium SaaS aesthetic—taking visual cues from tools like Vercel and Linear—PaletteLab allows users to upload any image and instantly receive a perfectly balanced, mathematically accurate color palette.

Because everything runs 100% in the browser, there are no file-size limits enforced by a backend, no privacy concerns with uploaded images, and near-instantaneous processing times.

---

✨ Key Features

• 🎨 Deep Pixel Extraction: Scans raw image data on an HTML5 Canvas to capture the truest representation of colors.
• 🧠 Smart Color Merging: Uses Euclidean distance algorithms in a 3D color-space to merge perceptually identical shades, ensuring every palette is distinctly diverse.
• 🔒 Absolute Locking System: Pin down your favorite colors. When regenerating or resizing the palette, locked colors maintain their exact visual position and raw percentage weight, dynamically re-distributing the remaining footprint to new colors.
• 🌙 Intelligent Dark Theme Generator: Automatically translates your extracted colors into a fully functioning UI mapping (Background, Surface, Primary, Secondary, Text) based on HSL luminance thresholds.
• 📥 High-Fidelity Exports: Generate physical PNG assets displaying your image, palette, and color breakdowns, or copy developer-ready code directly to your clipboard.

---

⚙️ How It Works (Under the Hood)

PaletteLab executes a sophisticated 3-step pipeline entirely on the client-side the moment an image is dropped:

1. Canvas Image Parsing

The uploaded file (via Browse, Drag & Drop, or Clipboard Paste) is drawn onto a hidden, down-scaled `` element. We read the raw `ImageData` array (a massive array of RGBA integers) to prevent UI blocking while maintaining high accuracy.

2. Median-Cut Quantization & Clustering

Rather than relying on basic K-Means (which is slow in JS), PaletteLab uses a fast histogram-based quantization algorithm. We bucket the millions of pixels into 64 deep clusters to find the most dominant pixel colors.

3. Perceptual Distance Merging

Since raw frequency can result in 5 slightly different shades of black, the application runs a post-processing loop using 3D Euclidean Distance (measuring the mathematical distance between RGB coordinates). If two colors are perceptually too similar, their weights are merged, and the lesser color is discarded. This guarantees vibrant, distinct palettes.

---

🛠️ Tech Stack & Architecture

PaletteLab was built with modern, scalable, and type-safe technologies:

• Frontend Framework: React 18 (Functional Components & Hooks)
• Language: TypeScript (Strict mode enabled for unbreakable component contracts)
• Build Tool: Vite (Lightning-fast HMR and optimized production bundling)
• Styling: Tailwind CSS v4 (Utility-first styling with a custom SaaS-inspired theme configuration)
• Typography: Alegreya (Elegant serif headings) & Lora (Clean serif body text) mapped securely via Google Fonts.
• Icons: Lucide React (Plus inline custom SVGs where brand icons were required)
• State Management: Custom React Hooks (usePalette, useDragAndDrop) to separate complex extraction logic from presentation layers.

---

📦 Export Formats

Designers and developers can export their generated palettes instantly into their specific workflow environments:

1. CSS Variables (:root scoped custom properties)
2. Tailwind CSS Config (Drop-in object for tailwind.config.js)
3. Figma Design Tokens (W3C standard JSON format for Figma plugins)
4. Raw JSON (Standard key-value pairs)
5. Canvas PNG (A generated graphic containing your uploaded image paired with the color swatches and their exact mathematical percentages).

---

🚀 Local Development

Getting the project up and running locally takes less than a minute.

# 1. Clone the repository
git clone https://github.com/S-K-Roy18/PaletteLab.git

# 2. Navigate into the directory
cd PaletteLab

# 3. Install NPM dependencies
npm install

# 4. Start the Vite development server
npm run dev

Visit http://localhost:5173 to view the application.

---

Built with precision and an eye for design.