AI Palette Generator 🎨

ai-palette is a powerful and flexible color palette generator for React applications that combines AI-powered suggestions with algorithmic color harmonies. Generate beautiful, harmonious color palettes from keywords, images, or let AI suggest the perfect colors for your project.

🌐 Demo: https://palette-demo.vercel.app

✨ Features

🎨 Two Generation Modes:
- AI Mode: Uses OpenAI's GPT to generate contextually relevant color palettes with detailed descriptions
- Basic Mode: Generates harmonious color palettes using advanced color theory algorithms
🌈 Multiple Color Harmonies:
- Analogous - Colors next to each other on the color wheel
- Complementary - Opposite colors that create strong contrast
- Triadic - Three colors equally spaced around the wheel
- Tetradic - Four colors in a balanced arrangement
- Monochromatic - Various shades of a single color
📊 Multiple Color Formats:
- HEX (#RRGGBB)
- RGB (Red, Green, Blue)
- HSL (Hue, Saturation, Lightness)
🖼️ Image-based Generation
📝 Detailed Color Descriptions
📋 One-Click Color Copy
🎯 Customizable Output Size
🔄 Real-time Updates
💅 Modern and Responsive UI
⚡ Fast and Lightweight
🔬 Smart Color Analysis
🎭 Accessibility Features

🚀 Quick Start

Installation

npm install ai-palette
# or
yarn add ai-palette

Basic Usage

import { AIPalette } from "ai-palette";

function App() {
    return (
        <AIPalette
            keyword="sunset"
            count={5}
            format="hex"
            type="complementary"
            mode="basic"
        />
    );
}

AI-Powered Mode

import { AIPalette, PaletteProvider } from "ai-palette";

function AppWithAI() {
    return (
        <PaletteProvider config={{ apiKey: "your_openai_api_key" }}>
            <AIPalette
                keyword="sunset"
                count={5}
                format="hex"
                type="complementary"
                mode="ai"
            />
        </PaletteProvider>
    );
}

📦 Compatibility

React Version: 16.8.0 or higher
Node Version: 14.0.0 or higher
TypeScript: Full type support included
Frameworks: Works with Next.js, Create React App, Vite, and more
Browsers: Modern browsers (Chrome, Firefox, Safari, Edge)

🛠️ Props & Configuration

AIPalette Component

Prop	Type	Default	Description
keyword	string	-	The theme or concept for generating colors
image	File	-	Image file for extracting colors
count	number	5	Number of colors to generate
format	'hex' \| 'rgb' \| 'hsl'	'hex'	Color format
type	'analogous' \| 'complementary' \| 'triadic' \| 'tetradic' \| 'monochromatic'	'default'	Color harmony type
mode	'ai' \| 'basic'	'basic'	Generation mode
onGenerate	(palette: Palette) => void	-	Callback when palette is generated
onError	(error: Error) => void	-	Callback when error occurs

PaletteProvider Props

Prop	Type	Description
config	{ apiKey?: string }	Configuration object for AI mode

🎯 Features in Detail

Generation Modes

Basic Mode

Uses advanced color theory algorithms
Generates harmonious color palettes instantly
Provides detailed descriptions of color characteristics
No API key required
Perfect for quick prototypes and basic needs

AI Mode

Uses OpenAI's GPT for intelligent color suggestions
Generates contextually relevant palettes
Provides rich, context-aware color descriptions
Requires OpenAI API key
Ideal for brand-specific and themed palettes

🎨 Color Harmonies

Analogous: Colors that are next to each other on the color wheel, creating smooth transitions
Complementary: Colors that are opposite each other, creating strong contrast
Triadic: Three colors equally spaced around the color wheel, offering balanced and vibrant combinations
Tetradic: Four colors arranged into two complementary pairs, providing rich and complex harmonies
Monochromatic: Different shades and saturations of the same color, perfect for subtle and sophisticated designs

🎭 Accessibility Features

WCAG contrast ratio calculations
Automatic text color adjustment
Color blindness simulation
Accessible color combinations

📝 Examples

Basic Mode Example

<AIPalette
    keyword="ocean"
    count={5}
    format="hex"
    type="analogous"
    mode="basic"
    onGenerate={(palette) => console.log("Generated palette:", palette)}
/>

AI Mode Example

<PaletteProvider config={{ apiKey: "your_openai_api_key" }}>
    <AIPalette
        keyword="sunset"
        count={5}
        format="rgb"
        type="complementary"
        mode="ai"
        onGenerate={(palette) => console.log("Generated palette:", palette)}
        onError={(error) => console.error("Error:", error)}
    />
</PaletteProvider>

Image-based Generation

<AIPalette
    image={imageFile}
    count={5}
    format="hsl"
    onGenerate={(palette) => console.log("Generated from image:", palette)}
/>

⚠️ Error Handling

The component includes built-in error handling for:

Invalid API keys
Network errors
Invalid image files
Unsupported color formats
Generation failures
Input validation errors

🤝 Contributing

We welcome contributions! Here's how you can help:

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Stay in Touch

Author: Fatih Güzel
GitHub: https://github.com/fatihguzel/ai-palette
Issues: https://github.com/fatihguzel/ai-palette/issues

Package detail

ai-palette

readme